Telegram Integration Guide

Connect your Sutra agents to Telegram and interact with your autonomous organization from anywhere. Approve high-risk actions with a tap, chat with agents on the go, and run project-scoped workflows — all from the messaging app you already use. Setup takes under five minutes.

Setup

1. Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts to name your bot.
  3. Copy the bot token provided by BotFather (e.g., 7123456789:AAH...).

2. Configure Sutra

Add the bot token to your Sutra instance. You can do this in the Sutra UI under Settings > Configuration (in the Integrations group) or by adding it to your .env file:

TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxxxxxx

Optionally, set a default chat ID for system-wide notifications (like approval alerts or agent online status):

TELEGRAM_DEFAULT_CHAT_ID=123456789

The bot starts automatically when the backend launches. You will see Starting Telegram bot... in the server logs.

Troubleshooting: If you don't see the "Starting Telegram bot..." message, double-check that your bot token is correct and hasn't been revoked. You can verify the token by visiting https://api.telegram.org/bot<YOUR_TOKEN>/getMe in a browser — if valid, it returns your bot's details in JSON.

Starting a Chat with the Bot

Private Chat (1-on-1)

  1. Open Telegram and search for your bot by its username (e.g., @YourSutraBotName).
  2. Open the chat and tap Start.
  3. Run /connect <agent-name> to link an agent (e.g., /connect Trader).
  4. Start talking! The bot sees all messages in a private chat and routes them to the connected agent.

Group Chat

  1. Create a new Telegram group.
  2. Add your Sutra bot to the group.
  3. Important: By default, bots can only see messages starting with a / (privacy mode). To let the bot see regular text messages:
  4. Go to @BotFather → /setprivacy → select your bot → Disable.
  5. Note: You must remove and re-add the bot to the group for this change to take effect.
  6. Run /connect <agent-name> in the group.

Tip: Use /chatid in any chat to see its Telegram chat ID (useful for manual configuration). Group IDs are usually negative numbers (e.g., -5205817399).

Security note: Disabling privacy mode means the bot can read all messages in the group — not just commands. Only add your Sutra bot to groups where you're comfortable with this level of access. For sensitive channels, keep privacy mode enabled and interact with the bot exclusively through / commands.

Connecting an Agent to a Chat

The easiest way to link an agent to a chat is directly from Telegram using the /connect command.

/connect Trader

The current chat is now permanently linked to the "Trader" agent. All messages sent here will auto-route to Trader, maintaining full conversation history.

  • To check the current connection: /connect
  • To switch to a different agent: /connect DevOps (This unlinks the previous agent and links the new one).
  • To unlink: /disconnect

Multiple Agents

If you want multiple agents available via Telegram, create separate Telegram groups for each agent: 1. Create a group (e.g., "Trading Bot Desk"). 2. Add your Sutra bot to the group. 3. In the group, run /connect Trader. 4. Repeat for other agents. Each group maintains an independent conversation with its specifically linked agent.

Commands

Command Description
/switch <agent> Switch active agent for the current session (keeps history per agent).
/switch Show which agent is currently active via switch.
/connect <agent> Link this chat to an agent persistently.
/connect Show which agent is linked to this chat.
/disconnect Unlink this chat from its agent.
/agents List all currently running agents in your Sutra instance.
/ask <agent> <message> Send a one-off message to a specific agent without switching context.
/project <name> Set the active project context for this chat.
/project list List all available projects in Sutra.
/project clear Remove the active project scope from this chat.
/newchat Start a fresh conversation (clears history context).
/chatid Show this chat's Telegram ID.
/status Check Sutra system status and health.
/forge <description> Start an autonomous feature build via Sutra Forge.

Command Examples

Here are some common usage patterns to get you started:

  • Quick research: /ask Researcher what are the latest trends in AI agent frameworks? — gets an answer from your Researcher agent without switching context.
  • Project-scoped work: /project MarketingQ3 then chat normally — all agent responses will be scoped to the Marketing Q3 knowledge base and context.
  • Feature request: /forge Add a dark mode toggle to the settings page — kicks off an autonomous code generation workflow that ends with a pull request.
  • Quick status check: /status — see if all your agents and infrastructure are healthy at a glance.

Talking to Agents: Switch vs. Connect

  • /switch: Best for private chats. Temporarily routes your messages to a different agent. If you switch back, the history is preserved.
  • /connect: Best for group chats. Permanently links the Telegram Chat ID to the agent in the Sutra database.
  • /ask: A one-off question to another agent (e.g., /ask DevOps is the server up?) without changing your currently connected agent.

Approvals via Telegram

When an agent requests human approval for a high-risk action (like deploying code or executing a trade), you will receive a Telegram notification complete with inline Approve and Reject buttons.

Approval Required

Deploy v2.3.1 to production

Agent: DevOps
Category: destructive | Risk: high
ID: a1b2c3d4

[Approve]  [Reject]

Tap a button to decide. The message updates to show the result, and the agent proceeds immediately—no need to open the Sutra web UI.

Routing Rules for Approvals: 1. If the requesting agent has a specific telegram_chat_id configured, the notification goes there. 2. Otherwise, it falls back to the global TELEGRAM_DEFAULT_CHAT_ID. 3. If neither is set, the Telegram notification is skipped (but remains visible in the Sutra Web UI).

Approval responses are instant — the moment you tap Approve or Reject, the agent resumes (or adjusts) its execution. There's no need to switch to the web dashboard for routine approvals, which makes Telegram ideal for teams that need to stay responsive to agent requests throughout the day.

Tip: Create a dedicated Telegram group called "Sutra Approvals" and set it as your TELEGRAM_DEFAULT_CHAT_ID. Add your team leads to this group so any available manager can handle approvals — this prevents bottlenecks when one person is unavailable.