Telegram Bot
A RocketRide source node that connects a Telegram bot to your pipeline, routing incoming messages to typed lanes and returning pipeline answers to the sender.
What it does
A source node (telegram://) that authenticates with a bot you create via @BotFather and listens for incoming messages. It handles text and media alike: photos, audio, voice notes, video, and documents are each downloaded (up to Telegram's 20 MB bot file limit) and routed to the matching pipeline lane. The first answer produced by the pipeline is sent back to the originating chat via sendMessage automatically.
Talks to the Telegram Bot API directly over aiohttp with no Telegram SDK dependency. In webhook mode the incoming POST route is served by the node's built-in FastAPI web server.
Both new and edited messages are processed. Unsupported message types (stickers, locations, polls, and so on) are silently ignored.
Configuration
Lanes
The node is a pipeline source. Its _source lane emits to text, image, audio, video, and tags. Each Telegram message type maps to one output lane:
| Telegram message | Output lane | Notes |
|---|---|---|
| Text | text | Written as plain text. |
| Photo | image | The largest available photo size is downloaded; MIME type image/jpeg. |
| Audio | audio | MIME type from the message, default audio/mpeg. |
| Voice note | audio | MIME type from the message, default audio/ogg. |
| Video | video | MIME type from the message, default video/mp4. |
| Document (PDF, Word, etc.) | tags | Written as tagged stream data; connect a Parser node downstream. |
Entry URLs are built as telegram://<chat_id>/<uuid> for text messages and telegram://<chat_id>/<file_id> for files.
Fields
| Field | Type | Description |
|---|---|---|
botToken | string | Telegram bot token from @BotFather (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11) |
mode | string | Default "polling". Polling works anywhere without a public URL. Webhook requires a public HTTPS endpoint. |
webhookUrl | string | Public HTTPS URL Telegram will POST updates to (e.g. https://your-server.com/telegram/webhook). Required for webhook mode. |
The node tile in the UI shows the currently configured mode.
The monitor info panel shows the last 6 characters of the configured bot token so you can verify which bot is connected without exposing the full secret.
Connection modes
Polling
The default. The node long-polls the Telegram getUpdates API in a background task using a 30-second server-side timeout and a batch size of up to 100 updates. The offset is advanced after each processed update, so acknowledged messages are never re-delivered. On network or API errors the loop sleeps 5 seconds then retries. Any previously registered webhook is cleared at startup because Telegram refuses getUpdates while a webhook is active.
Webhook
For production deployments with a public HTTPS endpoint. At startup the node registers telegram.webhookUrl with Telegram via setWebhook along with a freshly generated random secret token. Incoming POSTs are validated against the X-Telegram-Bot-Api-Secret-Token header; requests with a wrong or missing secret are rejected with HTTP 403. Each accepted update is handled concurrently as a background task. In-flight handlers are awaited during shutdown, and the webhook is deregistered via deleteWebhook when the pipeline stops.
The local POST route is derived from the path portion of telegram.webhookUrl, falling back to /telegram/webhook if the URL contains no path. Your reverse proxy or tunnel must forward that path to the node's web server port.
Replies
After a message runs through the pipeline, the first answer in the pipeline response is sent back to the originating chat. Replies longer than Telegram's 4096-character limit are truncated with a trailing ellipsis (...). If the pipeline produces no answers, nothing is sent. Reply failures are logged via debug() and never crash the update handler.
Limits & behavior notes
- 20 MB file cap -- Telegram's Bot API limit for downloads. The node checks the size reported by
getFileand skips larger files silently. - One answer per message -- only the first pipeline answer is returned to the chat; additional answers are discarded.
- Missing token -- if
telegram.botTokenis empty the node reportsTelegram Bot: missing bot tokenin the monitor and stays idle. - Byte accounting -- processed message and file sizes are reported to the monitor as completed or failed bytes via
monitorCompleted/monitorFailed.
Authentication
This node requires a Telegram bot token. Create a bot by messaging @BotFather on Telegram and following the /newbot flow. Copy the token BotFather provides and paste it into the telegram.botToken field.
No additional OAuth or API key registration is needed beyond the bot token.
Schema
| Field | Type | Description | Default |
|---|---|---|---|
Pipe.source.parameters | Bot Configuration | ||
telegram.botToken | string | Bot Token Telegram bot token from @BotFather (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11) | |
telegram.mode | string | Connection Mode Polling works anywhere without a public URL. Webhook requires a public HTTPS endpoint. | "polling" |
telegram.webhookUrl | string | Webhook URL Public HTTPS URL Telegram will POST updates to (e.g. https://your-server.com/telegram/webhook). Required for webhook mode. |
Dependencies
aiohttp>=3.13.5requestsfastapi