Telegram Integration
Connect agents to Telegram bots. Supports direct messages, group chats, @mentions, and reply threading.
How to connect an agent to Telegram
1:118 chapters
Build an AI Recruiter Agent — Telegram bot setup
Jun 2026
Concepts
public_chat_url) to be set under Settings → General.Bot Setup (BotFather)
Before connecting to Trinity, create and configure your bot via @BotFather on Telegram.
Step 1: Create the Bot
Open Telegram and message @BotFather
Send /newbot
Enter a display name (e.g., "My Agent Bot")
Enter a username ending in bot (e.g., my_agent_bot)
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:
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
| Command | Purpose |
|---|---|
| /setdescription | What users see when they open your bot |
| /setabouttext | Shown in the bot's profile |
| /setuserpic | Bot avatar (or use Trinity's avatar generator) |
Connect Bot to Agent
Open the agent detail page
Select the Channels tab and find the Telegram row under Channels
Click Configure — the Telegram configuration opens in a dialog
Paste your bot token and click Connect Bot
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
| Status | Meaning |
|---|---|
| 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:
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.
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:
Immediate acknowledgement — a 👀 reaction lands on your message the moment the agent picks it up. It is cleared when the turn ends.
Typing indicator — the standard Telegram "typing…" state.
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.
| Constraint | Limit |
|---|---|
| Duration | 5 minutes |
| File size | 10 MB |
| Config required | A 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:
| Command | Action |
|---|---|
| /start | Welcome message |
| /help | Shows capabilities |
| /reset | Clears 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. |
| /logout | Clear verified email |
| /whoami | Show 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:
Trigger Modes
| Mode | Bot Responds To | Context the reply uses | Privacy Mode |
|---|---|---|---|
| Mention only (default) | @mentions, replies to the bot, and /commands@yourbot | The 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 reply | Either — context needs Privacy Disabled |
| All messages | Every message in the group | The group's recent conversation | Must be Disabled |
| Observe | Every message, but the agent may stay silent | The group's recent conversation | Must 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:
| Badge | Meaning | What to do |
|---|---|---|
| Sees all messages | An un-tagged message has reached the bot in this group — context is on. | Nothing. |
| Tagged messages only | Privacy 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 yet | Privacy 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 off | You turned the Group context switch off for this group. | Turn it back on when you want it. |
/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.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
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/telegram | GET | Bot binding status; webhook_url only while it is registered under the current Public URL, and public_url_set |
| /api/agents/{name}/telegram | PUT | Configure bot token |
| /api/agents/{name}/telegram | DELETE | Remove bot binding |
| /api/agents/{name}/telegram/test | POST | Verify 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/groups | GET | List group configs |
| /api/agents/{name}/telegram/groups/{id} | PUT | Update 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} | DELETE | Deactivate group config |
| /api/agents/{name}/telegram/groups/{chat_id}/messages | POST | Post 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-indicator | PUT | Turn 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
/setprivacy, verify it shows "Disabled""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
See Also
Trinity docs
External references