n8n community node for sending messages via Telegram Bot API with retry, rate limit handling and auto-split
npm install n8n-nodes-telegram-gatewayA robust n8n community node for sending messages via Telegram Bot API with automatic retry, rate limit handling, and message auto-splitting.
- Send Message operation with full Telegram Bot API support
- Automatic retry with exponential backoff for network errors and server failures
- Rate limit handling with configurable behavior (retry or fail)
- Auto-split long messages to comply with Telegram's 4096 character limit
- Parse modes: Plain text, MarkdownV2, HTML
- Silent messages and link preview control
1. Go to Settings > Community Nodes in your n8n instance
2. Click Install a community node
3. Enter n8n-nodes-telegram-gateway
4. Click Install
``bash`
cd ~/.n8n/custom
npm install n8n-nodes-telegram-gateway
Then restart n8n.
Add to your Docker environment:
`yaml`
environment:
- N8N_CUSTOM_EXTENSIONS=n8n-nodes-telegram-gateway
Or mount the package:
`yaml`
volumes:
- ./custom-nodes:/home/node/.n8n/custom
1. Create a bot via @BotFather on Telegram
2. Copy the bot token
3. In n8n, go to Credentials > Add Credential > Telegram Bot API
4. Paste your bot token
5. Click Save
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| Chat ID | string | - | Target chat ID or @username |
| Text | string | - | Message text to send |
| Parse Mode | select | Plain | Plain / MarkdownV2 / HTML |
| Disable Web Page Preview | boolean | false | Disable link previews |
| Silent | boolean | false | Send without notification sound |
| Auto Split | boolean | false | Split messages > 4096 chars |
| On Rate Limit | select | Retry | Retry / Fail on 429 |
| Max Retries | number | 3 | Max retry attempts |
| Base Delay (ms) | number | 1000 | Base delay for backoff |
The node returns:
`json`
{
"ok": true,
"chatId": "-1001234567890",
"messageId": 123,
"attempts": 1,
"rateLimitHit": false
}
When Auto Split is enabled and message is split:
`json`
{
"ok": true,
"chatId": "-1001234567890",
"messageIds": [123, 124, 125],
"attempts": 3,
"rateLimitHit": false
}
If rate limit was encountered:
`json`
{
"ok": true,
"chatId": "-1001234567890",
"messageId": 123,
"attempts": 2,
"rateLimitHit": true,
"retryAfter": 30
}
``
[Manual Trigger] → [Set] → [Telegram Gateway] → [...]
1. Add Telegram Gateway node
2. Select your Telegram Bot API credentials
3. Set Chat ID (e.g., -1001234567890 or @channelname)
4. Enter your message text
5. Execute
1. Enable Auto Split
2. Paste or generate long text content
3. The node will automatically split into multiple messages
For high-volume sending:
1. Set On Rate Limit to Retry
2. Increase Max Retries (e.g., 5)
3. Set Base Delay to 2000ms or higher
The node throws clear errors with Telegram's error codes:
- 400 - Bad Request (invalid chat_id, empty text, etc.)401
- - Unauthorized (invalid bot token)403
- - Forbidden (bot blocked by user)429
- - Too Many Requests (rate limited)
Use n8n's error handling or "Continue On Fail" for graceful error management.
- Docker Desktop installed and running
1. Install dependencies and build:
`bash`
npm install
npm run build
2. Prepare custom node and start n8n:
`bash`
npm run n8n:prepare
npm run n8n:up
3. Open http://localhost:5678 in your browser
4. Create a new workflow and add Telegram Gateway node
After making changes to the node code:
`bash`
npm run n8n:refresh
This will rebuild, copy to custom extensions, and restart n8n.
| Command | Description |
|---------|-------------|
| npm run n8n:up | Start n8n container |npm run n8n:down
| | Stop n8n container |npm run n8n:logs
| | View n8n logs |npm run n8n:restart
| | Restart n8n container |npm run n8n:refresh
| | Rebuild node and restart n8n |
n8n data (workflows, credentials, database) is stored in ./.n8n/ directory. This directory is git-ignored and should not be committed.
`bashInstall dependencies
npm install
MIT