n8n-nodes-telegram-gateway

A robust n8n community node for sending messages via Telegram Bot API with automatic retry, rate limit handling, and message auto-splitting.

Features

- 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

Installation

$3

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

$3

``bash
cd ~/.n8n/custom
npm install n8n-nodes-telegram-gateway
`

Then restart n8n.

$3

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
`

Setup

$3

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

Node Parameters

| 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 |

Output

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
}
`

Example Workflow

`
[Manual Trigger] → [Set] → [Telegram Gateway] → [...]
`

$3

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

$3

1. Enable Auto Split
2. Paste or generate long text content
3. The node will automatically split into multiple messages

$3

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

Error Handling

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.

Local Testing with n8n

$3

- Docker Desktop installed and running

$3

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

$3

After making changes to the node code:

`bash
npm run n8n:refresh
`

This will rebuild, copy to custom extensions, and restart n8n.

$3

| 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 |

$3

n8n data (workflows, credentials, database) is stored in ./.n8n/ directory. This directory is git-ignored and should not be committed.

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Lint

npm run lint

Format

npm run format
``

License

MIT