> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Connect a Telegram bot and verify incoming and outgoing messages.

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](https://docs.formation.texturehq.com/runtime/identity-linking.md)
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

| Telegram input | Formation meaning |
| - | - |
| `chat.id` | External reply destination and normal chat conversation key |
| `message_thread_id` in a forum supergroup | Separate conversation for each topic |
| `message_id` | Message identity within the conversation |
| `reply_to_message.message_id` | Explicit parent message |
| `from.id`, names and username | Participant identity and display name |
| `update_id` | Durable event claim, scoped to this bot |

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`](https://github.com/TextureHQ/formation/tree/main/internal/connector/telegram)
and [`internal/admin/telegram_connector.go`](https://github.com/TextureHQ/formation/blob/main/internal/admin/telegram_connector.go).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.