> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Plugin

{/* Run: pnpm run docs:sync-toolkit */}

Telegram channel and messaging tool for Beige agents.

## What It Provides

* **Channel**: A GrammY-based Telegram bot that routes user messages to agents and supports concurrent sessions per thread
* **Tool**: `telegram` command for agents to send proactive messages

## Configuration

Add to your `config.json5`:

```json5 theme={null}
{
  plugins: {
    telegram: {
      config: {
        token: "${TELEGRAM_BOT_TOKEN}",
        allowedUsers: [123456789],          // Telegram user IDs
        agentMapping: {
          default: "assistant",             // Which agent handles messages
        },
        defaults: {
          verbose: false,                   // Show tool-call notifications
          streaming: true,                  // Stream responses in real-time
        },
      },
    },
  },
  agents: {
    assistant: {
      model: { provider: "anthropic", model: "claude-sonnet-4-6" },
      tools: ["telegram"],                  // Enable the telegram tool
    },
  },
}
```

## Prerequisites

1. Create a Telegram bot via [@BotFather](https://t.me/BotFather)
2. Get your bot token
3. Get your Telegram user ID (message [@userinfobot](https://t.me/userinfobot))

## Bot Commands

Users interact with the bot via these commands:

| Command                   | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| `/start`                  | Show welcome message and all available commands                    |
| `/new`                    | Start a fresh conversation (old session preserved on disk)         |
| `/stop`                   | Abort the current operation immediately                            |
| `/compact`                | Summarise and compress conversation history to free context tokens |
| `/status`                 | Show session info: agent, model, context usage, and settings       |
| `/agent`                  | List available agents                                              |
| `/agent <name>`           | Switch to a different agent — conversation history preserved       |
| `/model`                  | List available models for the current agent                        |
| `/model provider/modelId` | Switch to a different model — conversation history preserved       |
| `/verbose on\|off`        | Toggle tool-call notifications                                     |
| `/v on\|off`              | Shorthand for `/verbose`                                           |
| `/streaming on\|off`      | Toggle real-time response streaming                                |
| `/s on\|off`              | Shorthand for `/streaming`                                         |

## Switching Agent or Model

Both `/agent` and `/model` change the current session **without losing history**:

* The `.jsonl` conversation file is kept on disk untouched
* Only the in-memory pi session is disposed and recreated
* The next message picks up from the same history with the new agent/model

**`/agent <name>`**\
Switches to a different configured agent. The new agent's system prompt, tools, and skills apply from the next message. Useful for routing the same conversation to a specialist agent mid-task.

```
/agent reviewer    → now handled by the "reviewer" agent
/agent             → list all available agents
```

**`/model provider/modelId`**\
Switches to any model in the current agent's allowed list (primary or fallback). The model must be listed under the agent's `model` or `fallbackModels` config.

```
/model anthropic/claude-opus-4-5    → switch to Opus
/model zai/glm-4.7                  → switch to GLM
/model                              → list available models
```

Both overrides are stored in session metadata and persist across gateway restarts. `/new` clears them (starting fresh resets to the agent's default).

## Message Reactions

The bot reacts to every user message to communicate processing state:

| Reaction | Meaning                                                      |
| -------- | ------------------------------------------------------------ |
| 👀       | Message received — the agent is processing it                |
| 🎉       | Processing finished — no more tool calls or LLM turns coming |
| 😢       | Processing failed — an error message follows in the chat     |

Reactions are set via the Bot API's `setMessageReaction`. They are silently skipped if the bot lacks reaction permissions in a channel or if the chat type doesn't support them (e.g. some supergroups).

**Steering messages** (sent while the agent is already running) get 👀 but not 🎉 — they don't own the session lifecycle.

## Concurrency & Steering

The plugin is fully non-blocking: the grammY handler returns immediately and sessions run as background tasks. This means:

* **Multiple threads run in parallel** — each chat/thread has its own session and they operate independently, simultaneously
* **Sending a message while the agent is running steers it** — exactly like pressing ESC in the TUI. The new message is injected as a steering interrupt; the agent finishes its current tool call, then processes your message. No need to wait or use `/stop` first
* **`/stop` for hard abort** — immediately aborts the current operation (LLM call + tool loop). The partial response (if any) is sent before the stop confirmation

## `/status` Output

`/status` shows the current model, context window usage, and settings:

```
Session Status

Agent: `assistant`
Chat: `123456789 / Thread: 42`
Model: `claude-sonnet-4-6`

Context
▓▓▓░░░░░░░ 38.5k / 200k (19.3%)

Settings
• Verbose: 🔇 off
• Streaming: ⚡ on
```

## `/compact` — Manual Compaction

Manually compresses the conversation history using an LLM summarisation pass:

* If a session is active when `/compact` is called, it is aborted first (built-in to pi's compaction)
* Works after a gateway restart — the session file is reloaded from disk automatically
* Shows tokens freed and the post-compaction context bar on success

```
✅ Compacted! Previous context: ~38.5k tokens.

Context now: ▓░░░░░░░░░ 4.2k / 200k (2.1%)
```

## Auto-Compaction Notifications

When the agent automatically compacts the context (threshold or overflow recovery), the bot sends a notification:

* `🗜️ Auto-compacting context…` when it starts
* `✅ Context auto-compacted (~Xk tokens).` on success
* For overflow recovery: `✅ Context auto-compacted (~Xk tokens). Retrying your request…`

## Error Handling

LLM errors (invalid API key, rate limits, model unavailable, etc.) are forwarded to the chat with user-friendly messages:

| Error                 | Message shown                                                                    |
| --------------------- | -------------------------------------------------------------------------------- |
| Invalid API key / 401 | 🔑 There's an API key issue. Please check the configuration.                     |
| Rate limited          | ⏳ The AI is a bit busy right now. I've automatically switched to a backup model. |
| All models failed     | ❌ All AI models failed. Last error: …                                            |
| Context too long      | 📏 This conversation is getting too long for the AI's memory.                    |
| Network issue         | 🌐 Network connection issue. Please try again.                                   |

## Tool Usage

Agents can send messages proactively:

```
telegram sendMessage <chatId> <text>
telegram sendMessage <chatId> --thread <threadId> <text>
```

Long messages (>4096 characters) are automatically split into multiple Telegram messages.

## Session Model

* Each Telegram chat gets a persistent session (survives gateway restarts)
* Forum topics (threads) each get their own independent session
* `/new` starts a fresh session; old conversation is preserved on disk
* Verbose and streaming settings are persisted per-session
* `/compact` and `/status` work even after a gateway restart — sessions are lazily restored from disk on demand