Telegram Integration
Connect agents to Telegram bots. Supports direct messages, group chats, @mentions, and reply threading.
Build an AI Recruiter Agent — Telegram bot setup
Jun 2026
Concepts
public_chat_url to be configured in Settings.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.
Connect Bot to Agent
Open the agent detail page
Select the Sharing 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.
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 Sharing 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 Google Gemini 2.0 Flash 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 | GEMINI_API_KEY set on the backend |
If transcription fails or GEMINI_API_KEY is not 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 |
| /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.
Trigger Modes
| Mode | Bot Responds To | Privacy Mode |
|---|---|---|
| Mention only (default) | @mentions and replies to bot | Either |
| All messages | Every message in the group | 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 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 → Sharing 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.
API
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/telegram | GET | Bot binding status |
| /api/agents/{name}/telegram | PUT | Configure bot token |
| /api/agents/{name}/telegram | DELETE | Remove bot binding |
| /api/agents/{name}/telegram/test | POST | Verify bot or send test message |
| /api/agents/{name}/telegram/groups | GET | List group configs |
| /api/agents/{name}/telegram/groups/{id} | PUT | Update trigger mode / welcome |
| /api/agents/{name}/telegram/groups/{id} | DELETE | Deactivate group config |
| /api/agents/{name}/telegram/progress-indicator | PUT | Turn the in-progress indicator on or off for this binding (human-only) |
Troubleshooting
Bot not responding in groups
/setprivacy, verify it shows "Disabled""Connected (no webhook)" warning
Configure public_chat_urlin Settings with your Trinity instance's publicly accessible URL. The webhook registers automatically.
Messages delayed or not arriving
Check backend logs for webhook errors, verify your public_chat_url is accessible from the internet, and look for 429 (rate limit) errors.
Limitations
GEMINI_API_KEY on the backend.