elizaos--eliza/plugins/plugin-telegram/README.md

# @elizaos/plugin-telegram

Telegram connector for elizaOS. Gives an Eliza agent the ability to send and receive messages across Telegram private chats, groups, supergroups, channels, and forum topics.

## What it does

- Runs a Telegraf long-poll bot connected to the Telegram Bot API.
- Routes incoming messages and reactions through the elizaOS runtime so configured actions, providers, and evaluators can respond.
- Syncs Telegram chats, users, and group membership into the runtime as Worlds, Rooms, and Entities.
- Handles forum topics as separate Rooms (channelId format: `<chatId>-<threadId>`).
- Supports outgoing buttons (`login` and `url` kinds) via the `TelegramContent.buttons` field.
- Provides HTTP setup routes for bot-token configuration and GramJS user-account login.
- Supports multiple bot accounts per agent via `character.settings.telegram.accounts`.

## Prerequisites

Create a bot via [@BotFather](https://t.me/BotFather) and copy the token it provides.

## Configuration

### Minimal (single bot, environment variable)

```env
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
```

The plugin reads the token from the runtime setting `TELEGRAM_BOT_TOKEN` or `process.env.TELEGRAM_BOT_TOKEN`.

### Via character settings

```json
{
  "name": "MyAgent",
  "settings": {
    "telegram": {
      "botToken": "123456:ABC-DEF...",
      "apiRoot": "https://api.telegram.org"
    }
  }
}
```

### Multi-account

```json
{
  "settings": {
    "telegram": {
      "accounts": {
        "supportBot": { "botToken": "111:aaa", "allowedChats": ["-100123456"] },
        "announcementsBot": { "botToken": "222:bbb" }
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | Yes (default account) | Bot token from @BotFather |
| `TELEGRAM_API_ROOT` | No | Override Bot API base URL (e.g. local Bot API server). Default: `https://api.telegram.org` |
| `TELEGRAM_ALLOWED_CHATS` | No | JSON array of chat ID strings the bot will respond to. If absent, all chats are allowed. Example: `["-100123456789"]` |
| `TELEGRAM_TEST_CHAT_ID` | No | Chat ID used by the live smoke-test suite |

## Enabling the plugin

The plugin auto-enables when the `telegram` connector key is present in the agent connector config. To load it explicitly, add it to the agent's plugin list:

```json
{
  "plugins": ["@elizaos/plugin-telegram"]
}
```

## Setup UI routes

The plugin mounts these HTTP routes (no plugin-name prefix) for the dashboard setup wizard:

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/setup/telegram/status` | Current pairing state |
| POST | `/api/setup/telegram/start` | Validate + save bot token |
| POST | `/api/setup/telegram/cancel` | Remove saved token |
| GET | `/api/setup/telegram-account/status` | GramJS user-account auth state |
| POST | `/api/setup/telegram-account/start` | Begin GramJS login |
| POST | `/api/setup/telegram-account/submit-code` | Submit OTP or 2FA password |
| POST | `/api/setup/telegram-account/cancel` | Tear down GramJS session |

## Sending buttons

Include a `buttons` array in any `Content` object returned to Telegram:

```typescript
callback({
  text: "Welcome! Click below to authenticate.",
  buttons: [
    {
      kind: "login",
      text: "Authenticate",
      url: "https://your-app.example.com/auth",
    },
  ],
});
```

Supported `kind` values: `"login"` (Telegram login widget), `"url"` (plain URL button).

## Owner pairing

The plugin registers a `/eliza_pair <code>` bot command that lets the Telegram user matching a 6-digit code shown in the agent dashboard bind their Telegram identity to the owner account. Rate-limited to 5 attempts per minute per user.

## 409 Conflict errors

The Telegram Bot API permits only one active long-poll connection per token. If two agent processes share the same token simultaneously, Telegram rejects the second with a 409 error. The plugin stops the previous poller before launching a new one within the same process, but across separate processes you must ensure only one uses a given token at a time.

## Development

```bash
bun run --cwd plugins/plugin-telegram build
bun run --cwd plugins/plugin-telegram test
bun run --cwd plugins/plugin-telegram lint
```