LangBot/docs/event-based-agents/adapters/telegram.md

# Telegram EBA Adapter

## Status

Telegram has been migrated to the EBA adapter directory:

```text
src/langbot/pkg/platform/adapters/telegram/
├── adapter.py
├── api_impl.py
├── event_converter.py
├── manifest.yaml
├── message_converter.py
├── platform_api.py
└── types.py
```

The adapter is registered as `telegram-eba`.

## Configuration

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `token` | Yes | `""` | Telegram Bot API token from BotFather. |
| `markdown_card` | No | `true` | Whether to render Markdown card style replies. |
| `enable-stream-reply` | Yes | `false` | Whether to use Telegram streaming reply mode. |

## Events

Telegram declares these EBA events:

- `message.received`
- `message.edited`
- `message.reaction`
- `group.member_joined`
- `group.member_left`
- `group.member_banned`
- `bot.invited_to_group`
- `bot.removed_from_group`
- `bot.muted`
- `bot.unmuted`
- `platform.specific`

`platform.specific` is currently used for Telegram-only callback and chat-member update payloads that do not yet have a more specific common event type.

## Common APIs

| API | Status | Notes |
|-----|--------|-------|
| `send_message` | Supported | Supports text, image, file, and mixed message chains. |
| `reply_message` | Supported | Supports quoted replies through the original message event. |
| `edit_message` | Supported | Uses Telegram message editing APIs. |
| `delete_message` | Supported | Deletes messages where bot permissions allow it. |
| `forward_message` | Supported | Forwards a message between Telegram chats. |
| `get_group_info` | Supported | Uses Telegram chat metadata. |
| `get_group_member_list` | Supported | Telegram only exposes administrators through the Bot API; this returns the available member set. |
| `get_group_member_info` | Supported | Maps Telegram member status to EBA member roles. |
| `get_user_info` | Supported | Uses Telegram `get_chat` for user chat metadata. |
| `upload_file` | Not supported | Telegram has no standalone upload endpoint; files are uploaded as part of messages. The adapter raises `NotSupportedError`. |
| `get_file_url` | Supported | Returns the Bot API file URL. Test output redacts the bot token. |
| `mute_member` | Supported | Requires a supergroup and bot moderation permission. |
| `unmute_member` | Supported | Uses current `telegram.ChatPermissions` fields. |
| `kick_member` | Supported | Destructive; should only be run against disposable users/bots in tests. |
| `leave_group` | Supported | Destructive; should run at the end of a live test. |
| `call_platform_api` | Supported | See below. |

## Platform-Specific APIs

`call_platform_api(action, params)` supports:

- `pin_message`
- `unpin_message`
- `unpin_all_messages`
- `get_chat_administrators`
- `set_chat_title`
- `set_chat_description`
- `get_chat_member_count`
- `send_chat_action`
- `create_chat_invite_link`
- `answer_callback_query`

## Live Test Record

The live probe is:

```bash
uv run python tests/e2e/live_telegram_eba_probe.py --help
```

It supports private chat tests, group/supergroup tests, moderation tests, destructive tests, and a callback-only mode.

Verified on May 7, 2026:

- Private chat message APIs: send, reply, edit, delete, forward.
- Private chat media APIs: image/file sending and `get_file_url`.
- User API: `get_user_info`.
- Supergroup APIs: group info, member list, member info, administrators, member count, invite link.
- Supergroup mutation APIs: pin, unpin, unpin all, set title, restore title, set description, restore description.
- Moderation APIs: mute and unmute against a non-owner target bot.
- Destructive APIs: kick a disposable target bot, then make the test bot leave the test group.
- Event conversion observed for `message.received`, `group.member_banned`, `group.member_left`, `bot.removed_from_group`, and Telegram-specific chat-member updates.

The test fixed one real compatibility issue: `unmute_member` previously used Telegram's removed `can_send_media_messages` permission field. It now uses the split media permission fields required by current `python-telegram-bot`.

## Standalone Runtime Plugin E2E Record

Verified on May 10, 2026 with `EBAEventProbe`, SDK standalone runtime, Telegram Lite, `@rockchinq_bot`, and `Rock'sBotGroup`.

Evidence:

- Private chat JSONL: `data/temp/telegram-plugin-e2e-rerun.jsonl`
- Group chat JSONL: `data/temp/telegram-plugin-e2e-group.jsonl`
- Private media JSONL: `data/temp/telegram-plugin-e2e-media-ui.jsonl`

Observed and verified:

- `MessageReceived` reached the plugin with `bot_uuid=eba-telegram-live`, `adapter_name=telegram`, common sender/chat fields, and common `MessageChain` content.
- `BotInvitedToGroup` reached the plugin after adding the bot to `Rock'sBotGroup`.
- SDK API calls succeeded: `get_langbot_version`, `get_bots`, `get_bot_info`, `send_message`, plugin storage, workspace storage, `list_plugins_manifest`, `list_commands`, `list_tools`, and `list_knowledge_bases`.
- Outbound component sweep succeeded in private and group chats: plain text, mention text/equivalent, base64 image, quoted reply, file/document, and flattened forward fallback. Group mode also covered `AtAll` fallback behavior.
- Real Telegram Lite private-chat inbound media was verified through the plugin path: a sent document arrived as common `File`, and a sent photo arrived as common `Image`.
- Telegram platform API sweep succeeded for safe group actions: `get_chat_administrators`, `get_chat_member_count`, and `send_chat_action`.
- Common group/user APIs succeeded in group mode: `get_user_info`, `get_group_info`, `get_group_member_list`, and `get_group_member_info`.

Documented limits in this E2E run:

- Real Telegram UI inbound voice, sticker/emoji-as-common-component, and reply/quote messages were not completed in the plugin E2E evidence.
- `get_message`, `get_friend_list`, and `get_group_list` are not supported by this Telegram adapter.
- Mutating/destructive Telegram-specific actions such as pin/unpin, title/description changes, invite-link creation, moderation, kick, and leave were not repeated in the plugin run. They remain opt-in live-probe cases.
- Telegram does not expose a portable common `Face` component for native sticker/emoji semantics in the current adapter.

## Notes for Future Adapters

Telegram is the reference implementation for:

- Keeping platform-specific actions behind `call_platform_api`.
- Treating unsupported common APIs as explicit `NotSupportedError`.
- Marking destructive live test operations behind CLI flags.
- Redacting access tokens from live probe output.