Telegram

The Telegram integration connects a Telegram bot to your agent. Anyone who messages the bot receives responses from the agent in real-time, with streaming message updates as the agent works.

Prerequisites

• A Telegram account.
• An agent already created in Superagent.

Creating a Telegram Bot

Telegram bots are created through @BotFather, Telegram's official bot management tool.

1. Open Telegram and start a chat with @BotFather.
2. Send /newbot to BotFather.
3. Choose a display name for your bot (e.g., "My Assistant").
4. Choose a username for your bot. It must end in bot (e.g., my_assistant_bot).
5. BotFather will reply with your bot token -- a string that looks like 123456789:ABCdefGHIjklMNO.... Copy this token.

Keep the bot token secret. Anyone with this token can control your bot.

Connecting to Superagent

1. Open your agent in Superagent.
2. Open the chat integrations setup and select Telegram.
3. Paste your bot token into the Bot Token field.
4. Optionally click Verify token to confirm the token is valid. Superagent will display the bot's name and username on success.
5. Configure any additional settings (bot name, show tool calls, session timeout).
6. Click Connect.

Superagent will start long-polling the Telegram Bot API for incoming messages. Once connected, the integration appears in the sidebar under your agent.

Chat ID (Optional)

The Chat ID field is optional and auto-detected. When someone sends the bot a message, Superagent automatically captures the Telegram chat ID and uses it for routing. You do not need to fill this in unless you have an advanced use case.

Messaging Your Bot

After the integration is connected:

1. Open Telegram and find your bot by its username (e.g., @my_assistant_bot).
2. Send /start to begin a conversation. The bot will reply with a greeting.
3. Send any message. The agent will process it and the response will appear in the chat, updating progressively as the agent streams its output.

How Messages Flow

Telegram user sends message
        |
        v
Telegram Bot API (long polling)
        |
        v
Superagent routes to agent session
        |
        v
Agent processes message (tools, skills, etc.)
        |
        v
Response streams back to Telegram
(message updates in place as text arrives)

• Text messages are forwarded to the agent as-is.
• Photos and documents are downloaded and attached to the message sent to the agent. The agent can view images and read file contents.
• Inline keyboard buttons are used for interactive prompts (e.g., approval requests, multiple-choice questions).
• Long responses are automatically split into multiple messages if they exceed Telegram's 4096-character limit.
• Markdown formatting in agent responses is converted to Telegram-compatible HTML (bold, italic, code blocks, lists, tables).

Sessions

Each unique Telegram chat (each user who DMs the bot, or each group the bot is in) gets its own session in Superagent. In group chats, messages are prefixed with the sender's name so the agent can attribute who said what.

Send /clear at any time to reset the session. The bot will confirm, and your next message will start a new conversation.

Managing the Integration

Once connected, you can manage the integration from the Superagent sidebar:

• Pause / Resume -- Temporarily stop the bot from receiving messages without deleting the integration.
• Show Tool Calls -- Toggle whether the bot posts messages showing each tool the agent invokes.
• Session Timeout -- Set or change the inactivity timeout for automatic session rotation.
• Model and Effort -- Override the AI model or effort level used for this integration.
• Rename -- Change the display name shown in the sidebar.
• Delete -- Permanently remove the integration and disconnect the bot. Existing session history is preserved.