Telegram Integration
Receive Telegram text messages and send plain-text bot responses.
On this page
How Telegram works in NexFlow
Telegram sends updates to a NexFlow public HTTPS webhook. NexFlow accepts text messages from users, queues an asynchronous execution, and exposes normalized message data. Messages without text and messages from bots are ignored.
Create a Telegram Bot credential
- Create a bot with
@BotFatherin Telegram and obtain its bot token. - In NexFlow, open Credentials, select Add Credential, choose Telegram Bot, enter a name and the token, then save.
- Never share the token. NexFlow encrypts it and will not display it after saving.
Configure Telegram Trigger
- Add Telegram Trigger and set a unique Variable Name (default
telegram). - Choose the Telegram credential and save the node, then save the workflow.
- Reopen settings and select
Connect Webhook. NexFlow validates the bot, generates an HTTPS route, registers it with Telegram, and displays connection status and bot username. - Use
Copy URL,Refresh Status,Update Webhook, orDisconnectas needed. Refresh shows pending updates, last received time, and Telegram's last webhook error when available.
Public HTTPS is required
Telegram webhook connection rejects localhost and non-HTTPS application URLs. In local development, the UI instructs the operator to start the project's public development command. Quick Tunnel hostnames are temporary; select Update Webhook whenever the public URL changes.
Telegram variables
{{telegram.updateId}}
{{telegram.message.id}}
{{telegram.message.text}}
{{telegram.message.date}}
{{telegram.message.chat.id}}
{{telegram.message.chat.type}}
{{telegram.message.chat.username}}
{{telegram.message.from.username}}Optional chat and sender fields can be null. Chat and user IDs are normalized as strings for reliable templating.
Configure Send Telegram Message
| Setting | Behavior |
|---|---|
| Variable Name | Names the send result; default telegramMessage. |
| Telegram Credential | Required owned bot credential. |
| Chat ID | Recipient chat. Common value: {{telegram.message.chat.id}}. |
| Message | Plain text; templates such as {{aiText.text}} are supported. |
| Disable Notification | Requests a silent Telegram notification. |
Long text is split at sensible whitespace near Telegram's 4,096-character limit and sent sequentially. Output includes message ID, chat ID, date, complete source text, and chunk count.
Telegram troubleshooting
| Problem | How to fix it |
|---|---|
| Credential is required/unavailable | Select a saved Telegram Bot credential and save both node and workflow. |
| Webhook not configured | Save the trigger first, then Connect Webhook. |
| Bot stopped after a restart | Open the trigger and Update Webhook to the current public HTTPS URL. |
| Disconnected or pending updates | Refresh Status, review Telegram's last error, then Update Webhook if necessary. |
| Bot receives but does not respond | Check Executions, node connections, Chat ID, Message template, and the send credential. |
| No execution for a message | Send a non-empty text message from a user; non-text updates and bot-authored messages are ignored. |