All channels

Telegram bot

Connect a Telegram bot so that people who message it in a private chat are answered by your governed flow. Channel key: telegram.

What you need

  • A Telegram account and the @BotFather bot.
  • The bot token BotFather gives you (123456789:AAH…). That is the only thing you paste; the webhook is registered for you.
  • A public HTTPS origin for the channel gateway (CHANNEL_GATEWAY_PUBLIC_BASE_URL) — Telegram only delivers webhooks to https:// URLs on ports 443/80/88/8443.

Official documentation

Set up on Telegram

  1. Open Telegram, start a chat with @BotFather, send /newbot.
  2. Choose a display name and a username ending in bot (e.g. acme_support_bot).
  3. BotFather replies with the token. Keep it secret — anyone with it controls the bot. (Lost it? /token or /revoke in BotFather.)
  4. Optional: /setdescription, /setuserpic, and /setprivacy → Disable if you ever add the bot to groups and want it to see all messages (private chats always work).

Connect in Tools Anatomy

  1. /channels → Messaging channels → Telegram bot → Connect.
  2. Pick the flow, give the channel a name, paste the Bot token.
  3. On connect the gateway calls getMe (validates the token, stores the bot username) and setWebhook with the channel's webhook URL and a generated secret_token. Every incoming update carries X-Telegram-Bot-Api-Secret-Token; requests without the right value are rejected with 401. Nothing to paste in Telegram.
  4. Verify re-runs the same calls (safe to repeat; the secret is kept).

The token is stored in the Secret Manager; the generated webhook secret is stored alongside it. Neither is shown again.

Identity we derive

Canonical key Source Notes
external_user_id message.from.id (numeric Telegram user id) stable
channel telegram
display_name from.first_name + last_name runtime_only, user-controlled
phone_number only when the user shares their own contact card E.164
email —

conversation_context.channel_account_id = the bot's numeric id. Thread = the chat id (one conversation per private chat).

Limits

  • Text replies are split at 4096 characters (Telegram's sendMessage limit).
  • Media (photos, documents, voice notes…) is received as an attachment and answered with the flow's text-only policy; it is not downloaded.
  • Edited messages, channel posts and messages from other bots are ignored.
  • Telegram retries undelivered updates; deliveries are deduplicated on chat_id:message_id.

Test it

Open a chat with your bot, press Start, type a message. The reply appears in seconds; the thread and transcript show up under the channel in /channels.

Troubleshooting

  • Connect fails with "platform rejected the credentials" — the token is wrong or was revoked in BotFather.
  • Connect fails mentioning HTTPS — CHANNEL_GATEWAY_PUBLIC_BASE_URL must be the public https:// origin Telegram can reach.
  • Bot never answers — check GET https://api.telegram.org/bot<token>/getWebhookInfo (last_error_message explains delivery failures) or press Verify to re-register the webhook.