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

Method 1: Community Nodes (Recommended)

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

Method 2: npm install (Self-hosted)

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

Then restart n8n.

Method 3: Docker

Add to your Docker environment:

environment:
  - N8N_CUSTOM_EXTENSIONS=n8n-nodes-telegram-gateway

Or mount the package:

volumes:
  - ./custom-nodes:/home/node/.n8n/custom

Setup

Creating Credentials

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:

{
  "ok": true,
  "chatId": "-1001234567890",
  "messageId": 123,
  "attempts": 1,
  "rateLimitHit": false
}

When Auto Split is enabled and message is split:

{
  "ok": true,
  "chatId": "-1001234567890",
  "messageIds": [123, 124, 125],
  "attempts": 3,
  "rateLimitHit": false
}

If rate limit was encountered:

{
  "ok": true,
  "chatId": "-1001234567890",
  "messageId": 123,
  "attempts": 2,
  "rateLimitHit": true,
  "retryAfter": 30
}

Example Workflow

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

Basic Usage

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

With Auto-Split for Long Content

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

Handling Rate Limits

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

Prerequisites

• Docker Desktop installed and running

Quick Start

1. Install dependencies and build:

   npm install
   npm run build

2. Prepare custom node and start n8n:

   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

Development Workflow

After making changes to the node code:

npm run n8n:refresh

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

Useful Commands

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

Data Storage

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

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

License

MIT