Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Guides/Telegram Integration

Telegram Integration

Connect agents to Telegram bots. Supports direct messages, group chats, @mentions, and reply threading.

See it in the product

How to connect an agent to Telegram

1:11
8 chapters

Build an AI Recruiter Agent — Telegram bot setup

Jun 2026

Concepts

•1:1 Mapping — Each agent has its own dedicated Telegram bot. Bots cannot be shared across agents.
•Webhook — Trinity receives Telegram updates via a webhook URL. Requires the Public URL (public_chat_url) to be set under Settings → General.
•Trigger Mode — In groups, controls whether the bot responds to all messages or only @mentions and direct replies.
•Privacy Mode — A Telegram-level setting that determines which messages the bot receives in groups. Must be disabled for "all messages" mode to work.

Bot Setup (BotFather)

Before connecting to Trinity, create and configure your bot via @BotFather on Telegram.

Step 1: Create the Bot

1

Open Telegram and message @BotFather

2

Send /newbot

3

Enter a display name (e.g., "My Agent Bot")

4

Enter a username ending in bot (e.g., my_agent_bot)

5

Copy the bot token (format: 123456789:ABC-DEF...)

Step 2: Configure Privacy Mode (Required for Groups)

By default, Telegram bots have Privacy Mode enabled. This means in groups, the bot only receives @mentions, replies to its own messages, and bot commands.

To enable "all messages" mode in groups, you must disable Privacy Mode:

1

Message @BotFather

2

Send /setprivacy

3

Select your bot from the list

4

Choose Disable

Critical: If the bot is already in a group, you must remove and re-add the bot for the change to take effect.

Step 3: Optional Bot Settings

CommandPurpose
/setdescriptionWhat users see when they open your bot
/setabouttextShown in the bot's profile
/setuserpicBot avatar (or use Trinity's avatar generator)

Connect Bot to Agent

1

Open the agent detail page

2

Select the Channels tab and find the Telegram row under Channels

3

Click Configure — the Telegram configuration opens in a dialog

4

Paste your bot token and click Connect Bot

5

Trinity validates the token and registers the webhook

After connecting, the bot link (t.me/YourBot) appears in the UI. Users can start chatting immediately via direct messages, and group support is available once the bot is added to a group.

Webhook Status

StatusMeaning
Green "Connected"Bot configured, webhook active
Yellow "Bot connected, but Telegram can't deliver messages to it yet."Bot configured, but Telegram has no working webhook for it — messages won't be received

Telegram delivers messages to Trinity over the internet, so Trinity needs a public HTTPS address. The yellow warning says which case you are in:

•No Public URL is set. An admin sets it under Settings → General → Public URL (the warning links there; anyone else is told to ask an admin). Once saved, the bot registers automatically; nothing needs redoing in the dialog.
•The Public URL is set, but Telegram has not accepted the webhook. Check that the Public URL is reachable from the internet over HTTPS, then press Verify to retry.

Verify checks the whole path, not only the bot token. It reads Telegram's own record of the webhook, registers it when Telegram holds none or one for another address, and answers Operational beside the button only when Telegram can deliver. Otherwise it shows Not receiving messages, and the warning adds Telegram's own reason under Last attempt. A delivery error Telegram is still reporting while updates wait counts as not operational. The binding refreshes in place, and the result clears when you connect or disconnect the bot.

Message Flow

User sends message -> Telegram API -> Trinity webhook -> Agent -> Response -> Telegram

The agent receives the message text plus context for any media (photos, documents, voice notes). Responses are sent back as replies in the same chat.

Albums

When someone sends several photos or files together as an album, the agent gets them as one message: every file, in the order they were sent, with the album's caption. The agent answers once, not once per photo. Trinity waits about 1.5 seconds after the album's last item before handing it over, so an album takes slightly longer to start than a single photo.

•In a group, a mention in the album's caption (or a reply to the bot on any item) triggers the agent for the whole album. A mention in a single photo's caption counts as a mention too.
•An album can hold up to 10 files, and images in one album share a 10 MB total. An image past that limit is skipped, and the agent is told which one.
•Videos and audio files in an album are listed for the agent but it cannot open them.
•In a group with Privacy Mode on, Telegram only sends the bot messages that mention it. The other photos of a tagged album may never reach the bot, so the agent may see only the tagged one. Turn Privacy Mode off (see Step 2) if your group sends albums.

Formatting in Replies

Agent replies are written in Markdown and rendered as Telegram formatting: bold, italic, strikethrough, inline code, fenced code blocks (with syntax highlighting when a language is given), headings, links, bullet lists, horizontal rules, ||spoilers||, and > blockquotes (long ones collapse as expandable quotes). Tables are rendered as preformatted text. Literal <, > and &in a reply — a code snippet, an HTML tag, a comparison — survive intact instead of breaking the message's formatting. A reply longer than Telegram's 4,096-character limit is split into several messages, and each chunk keeps its formatting intact: a bold run or code block that straddles a cut is closed at the end of one chunk and reopened in the next. Proactive messages and completion reports use the same rendering.

Large code blocks stay inline in Telegram replies instead of being replaced by file references. The limit is counted the way Telegram counts it (emoji and other non-Latin characters can take two units each) and includes the formatting markup, so a chunk is never cut inside a tag or an HTML entity. Chunks are sent in order; if a chunk cannot be confirmed after the rate-limit retry or the plain-text formatting fallback, delivery stops before later chunks, and the chunks already confirmed are not sent again within that delivery attempt. A Telegram rate-limit wait of up to 30 seconds is honoured once; a longer wait stops delivery. A proactive message or completion report whose chunk cannot be confirmed reports failure; with automatic channel selection, the full message may then be sent through Slack or web even if its first chunks reached Telegram. A separate retry or crash recovery can still repeat earlier chunks. Unusually large nested formatting that leaves no room for text is dropped, and the remaining text is sent unformatted so nothing is lost.

Knowing the Agent Is Working

A Telegram-triggered task can run for minutes or hours. Three layers of feedback cover the wait, all of them optional and all fail-soft:

1

Immediate acknowledgement — a 👀 reaction lands on your message the moment the agent picks it up. It is cleared when the turn ends.

2

Typing indicator — the standard Telegram "typing…" state.

3

Elapsed-time note — if the turn passes 30 seconds, the bot posts a quiet "⏳ Working on it — N min elapsed" message (sent without a notification) and edits it in place about every minute. It is deleted when the turn finishes; if deletion isn't possible it is edited to a neutral "✔ Done." or "⚠️ Finished with an error."

This is on by default per bot binding, and can be turned off in the Telegram dialog on the agent's Channels tab. In groups it fires on @mentions and replies — a bot in observe mode stays silent, since a visible reaction would give away that it is listening.

If Telegram refuses any of it (reactions disabled for the chat, missing permissions), the rest still works and the turn is unaffected.

Completion Report-Back

When a task started from Telegram finishes later— because the agent delegated it, or kicked off background work — the result is posted back into the originating chat, threaded to your original message and sent by the same bot you were talking to. Failures report honestly (⚠️) rather than silently vanishing.

This fires only for work that inherited its Telegram context. An ordinary chat turn already answers inline, so it is never double-posted.

Group chats have a per-group consent flag (on by default) controlling whether the bot may post proactively there; turn it off and completion reports are suppressed for that group. Direct messages are consented by construction — you started the conversation.

Voice Messages

Voice notes sent to the bot are automatically transcribed with Gemini (gemini-3.5-flash unless GEMINI_TRANSCRIPTION_MODELsays otherwise) and delivered to the agent as text prefixed with the 🎤 emoji. Transcription is transparent — users just send voice notes normally.

ConstraintLimit
Duration5 minutes
File size10 MB
Config requiredA platform Gemini key — set in Settings → Integrations or as GEMINI_API_KEY on the backend (see Platform Keys)

If transcription fails or no Gemini key is configured, the agent receives a placeholder such as [Voice message received — transcription failed] so the conversation still progresses.

Voice Replies (Outbound)

The agent can also speak its replies as Telegram voice notes (OGG/Opus via sendVoice; in groups the note replies to the triggering message). This is a per-agent setting shared across all messaging channels — enable it with the Voice replies toggle inside the Telegram dialog. See Voice Replies for setup and fallback behavior.

Bot Commands

Users in Telegram can use these commands:

CommandAction
/startWelcome message
/helpShows capabilities
/resetClears conversation history
/login <email>Verify email for access-controlled agents. Code requests are capped (5 per sender, 3 per address and 20 per bot in 10 minutes); over a cap the bot says Too many sign-in code requests. Try again in 10 minutes.
/logoutClear verified email
/whoamiShow current verified email

Group Chat Configuration

When a bot joins a Telegram group, Trinity automatically creates a group config.

View and Manage Groups

Go to Agent Detail → Channels tab. Connected groups appear in the Telegram Groups section, and each group shows:

•Group name and type (group/supergroup)
•Whether the bot sees the whole conversation or only tagged messages (see Group context below)
•Current trigger mode
•Welcome message settings
•A Group context switch (on by default)

Trigger Modes

ModeBot Responds ToContext the reply usesPrivacy Mode
Mention only (default)@mentions, replies to the bot, and /commands@yourbotThe group's recent conversation, if the bot can see it (see Group context); otherwise just the tagged message plus the quoted message when the tag is a replyEither — context needs Privacy Disabled
All messagesEvery message in the groupThe group's recent conversationMust be Disabled
ObserveEvery message, but the agent may stay silentThe group's recent conversationMust be Disabled

If "all messages" mode doesn't work: Verify Privacy Mode is disabled in BotFather, then remove and re-add the bot to the group.

Group Context

When the bot can see the group's messages, the agent remembers what the group has been saying — who said what, for the last 40 messages within 24 hours — and a tagged turn is answered in that context. "@agent summarise what we decided" works without anyone re-pasting the thread. Un-tagged messages are only remembered; the agent still speaks only per the trigger mode, and remembering costs no agent turn.

Each group's entry in the Telegram dialog tells you where it stands:

BadgeMeaningWhat to do
Sees all messagesAn un-tagged message has reached the bot in this group — context is on.Nothing.
Tagged messages onlyPrivacy Mode is on, so Telegram delivers only @mentions and replies.In @BotFather send /setprivacy → Disable, then remove and re-add the bot to the group. Making the bot a group admin also works.
Not confirmed yetPrivacy Mode is off (or hasn't been checked), but nothing un-tagged has arrived here yet.If the bot joined before you turned Privacy Mode off, remove and re-add it. Press Verify to re-check Privacy Mode.
Context offYou turned the Group context switch off for this group.Turn it back on when you want it.
•Context is per group (and per topic in forum supergroups). Nothing from private chats or other groups is ever used in a group reply.
•The bot only ever remembers messages delivered while it is present — Telegram gives bots no history, so there is no backfill.
•/reset@yourbot in a group clears that group's remembered conversation for everyone. A bare /reset without the suffix does nothing in mention-only mode.
•Turn Group context off per group when a room should not be remembered at all (a legal or HR channel, say). Tagged turns then see only the tagged message, and nothing said in the group — including the agent's own replies — is stored. Switching it off also deletes what was already remembered, so switching it back on starts from a clean slate.

Group Authentication

By default, anyone in a group can chat with the bot. To require at least one verified member before the bot responds, go to Agent Detail → Channels tab → Channel Access Policy and set Group auth mode to "Any verified member". Once any group member completes /login, the group is unlocked for everyone.

Welcome Messages

Enable welcome messages to greet users who join the group. Toggle Welcome message on, enter the welcome text (up to 4096 characters), and use {name} to include the user's first name. The bot needs admin rights in the group.

Remove a Group

Click the remove button next to a group to deactivate it. The bot stops responding in that group but remains a member. To fully remove the bot, use Telegram's group settings.

API

EndpointMethodDescription
/api/agents/{name}/telegramGETBot binding status; webhook_url only while it is registered under the current Public URL, and public_url_set
/api/agents/{name}/telegramPUTConfigure bot token
/api/agents/{name}/telegramDELETERemove bot binding
/api/agents/{name}/telegram/testPOSTVerify the bot and its webhook (registering a missing one; webhook_registered and webhook_error in the answer), or send a test message
/api/agents/{name}/telegram/groupsGETList group configs
/api/agents/{name}/telegram/groups/{id}PUTUpdate trigger mode / welcome, plus the group's allow_proactive consent flag and its context_enabled (Group context) switch — those two are human-only
/api/agents/{name}/telegram/groups/{id}DELETEDeactivate group config
/api/agents/{name}/telegram/groups/{chat_id}/messagesPOSTPost a proactive message to a connected group (owner-gated, rate-limited; what send_group_message(channel_type: "telegram") calls). An optional idempotency_key / idempotency_ttl delivers the same message to the group once across runs — see MCP Server → Sending once across runs
/api/agents/{name}/telegram/progress-indicatorPUTTurn the in-progress indicator on or off for this binding (human-only)

Configure the bot programmatically:

# Connect bot to agent
curl -X PUT http://localhost:8000/api/agents/my-agent/telegram \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bot_token": "123456789:ABC-DEF..."}'

# Check status
curl http://localhost:8000/api/agents/my-agent/telegram \
  -H "Authorization: Bearer $TOKEN"

# Set group to respond to all messages
curl -X PUT http://localhost:8000/api/agents/my-agent/telegram/groups/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trigger_mode": "all"}'

Troubleshooting

Bot not responding in groups

1Check Privacy Mode: Message @BotFather, send /setprivacy, verify it shows "Disabled"
2Re-add the bot: Remove the bot from the group, then add it again
3Check trigger mode: In Trinity, verify the group is set to the expected trigger mode
4Check agent status: Ensure the agent container is running

"Bot connected, but Telegram can't deliver messages to it yet" warning

If no Public URL is set, set Public URL under Settings → General to your Trinity instance's publicly accessible HTTPS URL; the webhook registers automatically. If one is set, make sure it is reachable from the internet over HTTPS and press Verify: it re-registers the webhook and shows Telegram's reason if delivery still fails.

Messages delayed or not arriving

Check backend logs for webhook errors, verify your Public URL is accessible from the internet, and look for 429 (rate limit) errors.

Limitations

•One bot per agent — Each agent can only have one Telegram bot. Each bot can only be bound to one agent.
•Privacy mode is manual — Disabling Privacy Mode must be done through BotFather; it cannot be automated via the Bot API.
•Group re-add required — After changing Privacy Mode, the bot must be removed and re-added to existing groups.
•Welcome messages require admin — The bot needs admin rights in the group to see member join events.
•20MB file limit — Media files larger than 20MB cannot be processed.
•Voice transcription limits — Voice notes over 5 minutes or 10MB are rejected; transcription requires a platform Gemini key.
•No edited message handling — Edited messages are not re-processed.

See Also

Trinity docs

•Agent Sharing — the Channels tab that hosts the Telegram dialog
•Voice Replies — spoken replies across channels

External references

•Telegram Bot API — the API Trinity calls for webhooks, messages and reactions
•Telegram bot features: privacy mode — what a bot sees in groups, and why "all messages" mode needs it off