# Telegram

Use a private bot chat for messages, replies and approvals.

Use a dedicated bot you control. This release supports private text chats, replies and approve/deny buttons. Telegram groups, forum topics, native files and long polling are not supported.

## Set up the bot

1. Create the bot using [BotFather](https://t.me/BotFather). Save its token privately and note the numeric bot ID at the start of the token.
2. Choose **Integrations → Telegram → Add connection**. Supply the bot ID and token, plus a new webhook secret. Choose a default agent if you want new unthreaded messages to start a conversation with it.
3. Follow the connection's generated webhook instructions. Register its exact HTTPS callback and secret with Telegram. Use only the supported update types. Webhook delivery and `getUpdates` polling cannot be used together.

Do not drop pending Telegram updates while setting up or recovering the bot.

## Link and test

The person starts the bot's private chat. An authorized administrator links that bot ID and the person's immutable Telegram user ID in Beepgrid, then adds that exact user as a destination.

Set contact permissions separately. A username is not a stable identity and a group chat is not a supported destination.

Send a diagnostic message, find it in Telegram and reply to that exact message. Replying to a mapped message continues its conversation. New unthreaded text uses the configured default agent. Test approval buttons with a harmless request before using them for real decisions.

## Reconnect safely

Disabling the connection rejects callbacks and queued sends. Reconnecting requires a fresh webhook secret and Telegram registration so the old callback secret cannot resume access. A bot token rotation, if needed, is a separate BotFather action.

An ambiguous provider send may already have arrived. Reconcile its state before manually sending again. See [troubleshooting](https://beepgrid.com/docs/reference/errors.md).