Telegram Sink

The Telegram sink receives bot updates through long polling or a hosted webhook.

Choose a delivery style

| Style | Where it runs | Requirement | |---|---|---| | Long polling | Desktop adapter or Docker Compose sink service | Bot token and a continuously running process | | Webhook | Hosted Flow-Like API | Public HTTPS URL and a registered Telegram webhook |

Telegram permits one webhook configuration per bot. Delete the webhook before using the same bot token with long polling.

Configure the event

| Field | Meaning | |---|---| | bot_token | Token issued by BotFather | | webhook_secret | Secret Telegram sends with each webhook request | | chat_whitelist | In desktop polling mode, allow only these chat IDs when non-empty | | chat_blacklist | In desktop polling mode, always ignore these chat IDs | | respond_to_mentions | Process group messages that mention the bot | | respond_to_private | Process private messages | | command_prefix | Prefix that targets the bot in a group; defaults to / | | bot_name, bot_description | Display information for the event configuration |

Create and connect a bot

1. Open a conversation with @BotFather.
2. Run /newbot and copy the resulting bot token.
3. Paste the token into the Telegram event configuration.
4. Choose local or remote execution and activate the event.

Caution

The bot token grants control of the bot. Keep it out of source control, logs, screenshots, and shared shell history.

Hosted webhook setup

The event editor can register the webhook automatically. For manual setup, copy the generated webhook URL from Flow-Like and use the same secret stored on the event:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://flow-like.example/sink/trigger/telegram/<EVENT_ID>",
    "secret_token": "<WEBHOOK_SECRET>"
  }'

The Flow-Like route ends in /sink/trigger/telegram/{event_id}; your reverse proxy may add an API prefix. Prefer the URL generated by the event editor.

Check Telegram's current registration:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Return the bot to polling mode by deleting the webhook:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook"

Webhook security

For a hosted webhook, Flow-Like checks the active event sink, validates Telegram's source IP ranges outside local development, and compares the configured secret with X-Telegram-Bot-Api-Secret-Token.

The endpoint acknowledges a valid update immediately and dispatches the workflow asynchronously. A successful acknowledgement includes whether a run was triggered and its run ID.

Workflow payloads

Webhook delivery forwards Telegram's update JSON. A message update commonly contains update_id, message, message.chat, message.from, and message.text, but Telegram can send other update types.

Polling adapters build message-oriented context for the workflow and may include downloaded media or conversation context. Do not assume its shape is identical to the raw webhook update.

When a flow supports more than one delivery style, check the payload shape before reading nested fields.

Message filtering

Desktop polling applies filters in this order:

1. Reject a chat excluded by the whitelist or blacklist.
2. For a private chat, honor respond_to_private.
3. For a group, accept the configured command prefix.
4. Otherwise, accept a mention when respond_to_mentions is enabled.

Keep allowlists narrow for bots that can trigger privileged or costly workflows.

Troubleshooting

| Symptom | Check | |---|---| | Polling receives nothing | Remove the bot's webhook and keep the polling process running | | Webhook returns 401 | Secret configured on both Telegram and the event | | Webhook returns 403 | Proxy preserves the real client address and Telegram IP validation can see it | | Group messages are ignored | Prefix, mention setting, and chat filters | | Private messages are ignored | respond_to_private |