Telegram

Prerequisites

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

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.
3. Choose a display name for the bot (e.g., "My Assistant").
4. Choose a username. It must end in bot (e.g., my_assistant_bot).
5. BotFather replies with your bot token, a string like 123456789:ABCdefGHIjklMNO.... Copy it.

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

Connecting to Gamut

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

Gamut starts long-polling the Telegram Bot API for incoming messages, and the integration appears in the sidebar under your agent.

Chat ID (optional)

The Chat ID field is auto-detected: when someone messages the bot, Gamut captures the Telegram chat ID and uses it for routing. Leave the field blank unless you have an advanced use case.

Messaging your bot

1. Open Telegram and find the bot by its username (e.g., @my_assistant_bot).
2. Send /start. The bot replies with a greeting.
3. Send any message. The response appears in the chat, streaming as the agent works.

How messages flow

Telegram user sends message
        |
        v
Telegram Bot API (long polling)
        |
        v
Gamut routes to agent session
        |
        v
Agent processes message (tools, skills, etc.)
        |
        v
Response streams back to Telegram
(animated draft in DMs, in-place edits in groups)

• Text messages are forwarded to the agent as-is.
• Photos and documents are downloaded and attached to the message. The agent can view images and read file contents.
• Inline keyboard buttons are used for interactive prompts (e.g., approval requests, multiple-choice questions).
• Streaming: In DMs, the response streams as an animated draft. In groups, the bot edits the message in place as text arrives (editMessageText).
• Formatting: Responses are sent as rich messages (Bot API 10.1) with a 32768-character limit. When rich messages are unavailable, Markdown is converted to Telegram-compatible HTML (bold, italic, code blocks, lists, tables) with a 4096-character limit, and longer responses are split across messages.

Sessions

Each unique Telegram chat (each user who DMs the bot, or each group the bot is in) gets its own session in Gamut. 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 confirms, and the next message starts a new conversation.

Managing the integration

Once connected, manage the integration from the Gamut sidebar:

• Pause / Resume: Temporarily stop the bot from receiving messages without deleting the integration.
• Show Tool Calls: Toggle whether the bot posts a message for each tool the agent invokes.
• Session Timeout: Set or change the inactivity timeout for automatic session rotation.
• Model and Effort: Override the 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. Session history is preserved.