Telegram Bot System

CamelAGI runs a multi-bot Telegram architecture where a single process manages multiple independent bots. There are two bot types: admin bots (control plane) and agent bots (conversational AI). Each bot is backed by a grammY Bot instance and operates via long-polling.

Table of Contents

1. Multi-Bot Architecture
2. Bot Lifecycle
3. Admin Bot
4. Agent Bot
5. Draft Streaming
6. Group Support
7. Agent Resolution
8. Duplicate Token Detection
9. Polling with Retry and Backoff
10. Per-Agent Configuration
11. Access Control and Pairing
12. Config Examples

Multi-Bot Architecture

The system distinguishes between two bot roles defined per-agent in the YAML config:

Both types are grammY Bot instances stored in a shared activeBots map (Map<string, BotState>), keyed by agent ID.

BotState

Every running bot is tracked as a BotState:

interface BotState {
  bot: Bot;
  botInfo: { id: number; username: string };
  runtimeModels: Map<number, string>;              // per-chat model overrides
  runtimeThinking: Map<number, Config["thinking"]>; // per-chat thinking overrides
  runtimeEffort: Map<number, Config["effort"]>;     // per-chat effort overrides
}

Runtime maps let users switch model, thinking, and effort at runtime via /model, /think, and /effort without touching the config file. Overrides reset on /clear or process restart.

Entry Point

Telegram is loaded via the pluggable channel system (src/channels/). TelegramChannel in src/channels/telegram.ts wraps src/telegram.ts, which is the barrel module. startTelegram(getConfig, getSystemPrompt) iterates over all agents in the config, instantiates the correct bot type for each, and begins polling. It also handles a legacy path: if config.telegram.botToken is set and no agent reuses the same token, it starts a legacy agent bot with the ID "telegram".

Bot Lifecycle

Start (Initial)

startTelegram() is called once at process boot. For each agent with a telegram.botToken:

1. Duplicate token check (see below).
2. If agent.admin === true, dynamically imports setupAdminBot and creates the admin bot.
3. Otherwise, calls setupAgentBot to create an agent bot.
4. The bot’s getMe() is called to populate botInfo.
5. startPolling(bot, label) begins long-polling.

Hot-Start

startBot(agentId, botToken, getConfig, getSystemPrompt) starts a single bot after the process is already running. This is used by:

• The /newagent wizard (after admin approval).
• Config hot-reload.
• The /restart command.

A startingBots Set prevents double-starts. If a bot with the same ID is already in activeBots or startingBots, the call throws.

Stop

stopBot(agentId) stops polling, clears runtimeModels, and removes the bot from activeBots. Returns false if the bot was not found.

Restart

The admin bot’s /restart [agentId] command calls stopBot then startBot. Without an argument, it restarts all non-admin agent bots.

Full Shutdown

stopTelegram() stops all bots, clears the activeBots map, and unregisters the approval-forwarding bot.

Admin Bot

Source: src/telegram/admin-bot.ts

The admin bot is a management interface. It does not run AI conversations.

Commands

Callback Queries

The admin bot handles several callback query patterns:

Wizards

Wizards are step-by-step conversational flows driven by the wizard engine (src/telegram/wizard.ts). Each wizard is a WizardDef containing ordered steps, validation, and an onComplete handler.

Wizard Engine

• Wizards are stored per-chat in a Map<number, ActiveWizard>.
• Each wizard has a 10-minute timeout. If the user stops responding, the wizard auto-cancels and notifies the user.
• Steps can have inline-button options, free-text input, validate functions, transform functions, and skip predicates.
• The /cancel command or timeout cancels the active wizard.
• Only one wizard can be active per chat at a time.

Setup Wizard (/setup)

Walks through:

1. Provider – inline buttons: Anthropic, OpenAI, OpenRouter, Ollama, Custom.
2. API Key – free text (skipped for Ollama).
3. Base URL – free text (only for Custom provider).
4. Model – free text or pick from preset list.

On completion, saves provider, model, API key, and base URL to the config file.

Provider presets are defined in PRESETS:

New Agent Wizard (/newagent)

Walks through:

1. Name – free text, required.
2. SOUL.md – “Use default” (OpenClaw template) or “Customize” (inline buttons). If customized, prompts for a one-line description.
3. Model – For simple providers (Anthropic, OpenAI, Ollama): shows models as inline buttons, one per row. For OpenRouter: 2-step flow — pick provider first (2 per row with model counts), then pick model from that provider.
4. Telegram bot token – free text or “Skip — no Telegram bot” button.

On completion:

• Generates a unique slug ID from the name (e.g. “Personal Finance” becomes personalfinance).
• Validates the bot token by calling getMe against the Telegram API.
• Seeds the agent workspace (creates directories and bootstrap files).
• Saves the agent config.
• If a bot token was provided, sends a bot-approval request with Approve/Deny buttons. The bot only starts polling after admin approval.

Agent Bot

Source: src/telegram/agent-bot.ts

Agent bots handle AI conversations. Each agent bot runs the full orchestration pipeline (agent loop, tool calls, streaming).

Commands

Admin-only commands (/agents, /soul, /sessions, /config, /setup, /newagent, /deleteagent, /pairing, /restart) are intercepted and redirect to the admin bot with a clickable @username link. This prevents accidental LLM token usage on management commands.

Message Handling

Text Messages

When a text message arrives:

1. Group filtering – In groups with mentionOnly enabled, the bot only responds if the message mentions @botUsername or is a reply to one of the bot’s messages.
2. Mention stripping – @botUsername is removed from the message text.
3. Empty check – If the cleaned text is empty, the message is ignored.
4. Active run check – If a run is already active for this session, the message is queued via queueOrProcess.
5. Orchestration – The message enters the full orchestration pipeline:
   • A DraftStream is created for live message editing.
   • Reactions are set on the user’s message to indicate status:
     • eyes – message received
     • thinking_face – processing started
     • wrench – tool call in progress
     • thought_balloon – thinking/reasoning active
     • lock – approval required
   • The onEvent callback routes stream_text, chunk, tool_call, thinking, subagent_start, and approval_request events.
   • For approval requests, an inline keyboard with Allow / Always / Deny buttons is sent.
6. Response delivery – After orchestration completes:
   • If the response fits in the draft message (under 4096 chars), the draft is flushed as the final message.
   • If the response exceeds 4096 chars, the draft message is deleted and the response is sent via sendChunked.
   • If no draft message was created, sendChunked sends the full response.
7. Error handling – On failure, the error message replaces the draft message text, or is sent as a new message.

Voice Messages

When a voice or audio message arrives:

1. Checks if voice transcription is configured (config.voice.enabled).
2. If not configured, replies with a hint to set it up in the admin bot.
3. Downloads the audio file via Telegram API (max 20 MB).
4. Sends it to the configured transcription provider (Groq/OpenAI/Deepgram).
5. Passes the transcribed text as [Voice] <text> to the shared handleIncoming handler.
6. The message then follows the same orchestration flow as text messages.

Approval Callback Queries

Agent bots handle tool-approval callbacks:

Session IDs

Sessions are scoped per-agent and per-chat:

• Legacy bot: telegram-<chatId>
• Named agent: <agentId>-<chatId>

Draft Streaming

Source: src/telegram/draft-stream.ts

Draft streaming provides a “live typing” effect by repeatedly editing a single Telegram message as the LLM generates tokens.

How It Works

1. createDraftStream(chatId, api, opts?) returns a DraftStream with three methods: update(text), flush(), and getMessageId().
2. On the first update() call, once the text exceeds minInitialChars (default: 30 characters), a new message is sent via sendMessage.
3. Subsequent update() calls schedule a throttled editMessageText to avoid hitting Telegram rate limits.
4. flush() performs a final edit with the complete text.

Throttling

• Default throttle interval: 1200ms between edits.
• A timer tracks elapsed time since the last edit. If an update arrives before the throttle window expires, it is buffered and sent when the timer fires.
• Only the latest text is kept; intermediate states are dropped.
• Duplicate edits (same text) are skipped.

Message Size Limit

All text is truncated to 4096 characters (Telegram’s message limit) before sending or editing. If the final response exceeds 4096 characters, the agent bot deletes the draft message and re-sends via sendChunked, which splits the response into multiple messages using the BlockChunker (800-3500 chars per chunk, paragraph-break preference).

Group Support

Source: src/telegram/helpers.ts

Group Detection

isGroupChat(chatType) returns true for "group" and "supergroup" chat types.

Mention-Only Mode

When mentionOnly is true (the default for named agents), the bot only responds in groups if:

• The message text contains @botUsername, OR
• The message is a direct reply to one of the bot’s previous messages (checked via reply_to_message.from.id === botId).

All other messages in the group are silently ignored.

Mention Stripping

Before processing, stripMention(text, botUsername) removes all occurrences of @botUsername (case-insensitive) from the message text so the AI does not see the mention as part of the user’s question.

Unauthorized Users in Groups

If an unauthorized user sends a message in a group, the bot silently ignores it rather than replying with an access-denied message (to avoid noise in shared groups).

Agent Resolution

Source: src/telegram/resolve.ts

resolveAgent(agentId, config, globalSystemPrompt, overrides?) produces a ResolvedAgent object that merges agent-specific config with global defaults. The overrides parameter accepts { model?, thinking?, effort? } for per-chat runtime overrides. This is called on every message, so config changes take effect immediately without restarting the bot.

Resolution Rules

The runtime model override (set via /model) takes highest priority but only persists in memory.

ResolvedAgent Type

interface ResolvedAgent {
  id: string;
  name: string;
  model: string;
  systemPrompt: string;
  thinking: Config["thinking"];
  effort: Config["effort"];
  maxTurns: number;
  allowedUsers: number[];
  mentionOnly: boolean;
}

Duplicate Token Detection

startTelegram() prevents two bots from polling with the same Telegram bot token, which would cause a 409 Conflict error from the Telegram API.

The detection works in two passes:

1. Collect agent tokens – All agent.telegram.botToken values are gathered into a Set.
2. Legacy token check – The top-level config.telegram.botToken is only used if no agent already claims the same token.
3. Agent loop – As each agent’s token is processed, it is added to a usedTokens Set. If a subsequent agent has the same token, it is skipped with a console warning:

   [agentId] skipped -- duplicate bot token (already used by another agent)
   

Polling with Retry and Backoff

Source: src/telegram/helpers.ts – startPolling(bot, label)

Polling uses grammY’s bot.start() with drop_pending_updates: true to avoid processing messages that arrived while the bot was offline.

Retry Strategy

If polling fails:

• 409 Conflict (another instance polling the same token) or network errors (ECONNRESET, ETIMEDOUT, ENOTFOUND, fetch failed): retry after a delay with exponential backoff.
• Other errors: treated as fatal; logged but not retried.

Backoff Parameters

The delay resets to the initial value on successful connection (inside onStart).

Per-Agent Configuration

Each agent can override global defaults. The resolution chain is: runtime override > agent config > global config.

Configurable Fields per Agent

Access Control and Pairing

Both admin and agent bots enforce access control when allowedUsers is non-empty. The flow for unauthorized users:

1. User sends a message.
2. Bot checks allowedUsers (in-memory config, then file fallback).
3. If not found, a pairing request is created with a short code.
4. The admin bot is notified with Approve/Deny inline buttons.
5. On approval, a 5-digit OTP is generated. The user is prompted to enter it.
6. On successful OTP verification, the user is added to an in-memory otpVerifiedUsers set and gains access for the process lifetime.

In groups, unauthorized users are silently ignored (no access-denied replies).

Config Examples

Minimal: Single Agent Bot

apiKey: sk-xxx
model: claude-sonnet-4-20250514
provider: anthropic

agents:
  assistant:
    name: Assistant
    telegram:
      botToken: "123456:ABC-DEF"
      allowedUsers: [12345678]

Admin + Multiple Agents

apiKey: sk-xxx
model: claude-sonnet-4-20250514
provider: anthropic

agents:
  admin:
    name: Admin
    admin: true
    telegram:
      botToken: "111111:ADMIN-TOKEN"
      allowedUsers: [12345678]

  coder:
    name: Coder
    model: claude-opus-4-20250514
    thinking: high
    systemPrompt: "You are a senior software engineer."
    telegram:
      botToken: "222222:CODER-TOKEN"
      allowedUsers: [12345678]

  writer:
    name: Writer
    model: gpt-4o
    effort: high
    telegram:
      botToken: "333333:WRITER-TOKEN"
      allowedUsers: [12345678]
      groups:
        mentionOnly: true

Agent with Custom Provider

apiKey: sk-or-xxx
model: anthropic/claude-sonnet-4-20250514
provider: openai
baseUrl: https://openrouter.ai/api/v1

agents:
  helper:
    name: Helper
    model: google/gemini-2.5-pro
    telegram:
      botToken: "444444:HELPER-TOKEN"

Legacy Top-Level Telegram Config

This form is still supported but discouraged. The agent ID is "telegram" and the session ID format is telegram-<chatId>.

apiKey: sk-xxx
model: gpt-4o
provider: openai

telegram:
  botToken: "555555:LEGACY-TOKEN"
  allowedUsers: [12345678]
  groups:
    mentionOnly: true

Source Files