Skip to main content
A Telegram bot gives an agent a messaging identity in private chats, groups and forum topics. It uses the same perspective, memory, addressing and run pipeline as the Slack connector.

​
Set up Telegram

  1. Create a bot for this agent through Telegram’s BotFather and obtain its token.
  2. Choose Telegram in agent setup, or add a Telegram connection to an existing agent. Paste the token and save.
  3. Formation verifies it with getMe, stores the bot token and a generated webhook secret encrypted, activates the connector and registers its webhook.
  4. Open the bot in Telegram and send a message. For group use, add it to the group and verify that the bot’s Telegram privacy settings allow the messages you expect it to receive.
The deployment needs a reachable HTTPS PUBLIC_URL. If webhook registration fails after saving, the saved connector remains; retry registration by saving again. Formation reuses an existing readable webhook secret so a failed registration attempt does not invalidate the old webhook’s authentication. One agent can have both Slack and Telegram connections. Their conversations remain separate until explicitly supported identity linking establishes the relevant account relationship within the agent’s perspective.

​
Authentication and supported input

POST /telegram/events/{botID} selects the connector by the bot’s numeric ID. Formation verifies X-Telegram-Bot-Api-Secret-Token against that connector’s encrypted webhook secret. Unknown bots and bad secrets receive the same 401. The connector handles text-bearing message updates. Edits, channel posts, callback queries, media-only messages, messages without a sender, self echoes and completed duplicate updates are acknowledged without starting a new turn. Telegram formatting entities and attachment extraction are not supported by this connector’s current message path.

​
Conversations and replies

The namespace comes from the stored connector, not the incoming request. Private chats are direct conversations; groups use the shared addressing policy. A bot mention uses its @username; its numeric ID is used for self-recognition. Formation renders canonical Markdown to Telegram HTML and splits long replies into bounded parts. Group replies carry message linkage and forum-topic replies keep the topic ID. Private replies do not need an extra reply link. Stored canonical content remains independent of the Telegram render format. The dashboard can resolve current conversation names through getChat. Stored names and routing identifiers remain fallbacks when lookup fails.

​
Progress and failures

Best-effort message reactions signal working (👀), completion with a platform-supported topic emoji, and failure (👎). A chat may restrict reactions; a reaction failure does not suppress the reply. Ingress uses durable event claims and the shared dispatcher. Inspect the conversation’s engagement decision and run outcome when a reply is missing. If no incoming messages appear at all, check the bot token, webhook registration, public hostname and Telegram-side chat settings first. Implementation: internal/connector/telegram and internal/admin/telegram_connector.go.