Telegram Integration
Connect agents to Telegram bots. Supports direct messages, group chats, @mentions, and reply threading.
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
In the Telegram section, paste your bot token
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.
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.
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 |
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.