# Telegram Bot API Integration

## Overview

OpenClaw's Telegram channel supports bot communication via the Bot API, with long-polling as the default delivery mechanism. The system handles both direct messages and group conversations with distinct session isolation.

## Setup Steps

1. **Create a bot token** through @BotFather on Telegram
2. **Configure the token** via environment variable (`TELEGRAM_BOT_TOKEN`) or config file (`channels.telegram.botToken`)
3. **Start the gateway** - Telegram initialization occurs automatically when a valid token resolves
4. **Approve pairings** for DM access (default behavior requires code confirmation)

## Core Capabilities

### Message Handling

- DM conversations share the agent's main session
- Group messages remain isolated with session keys formatted as `agent:<agentId>:telegram:group:<chatId>`
- Replies deterministically route back through Telegram; the model cannot select alternative channels

### Formatting & Media

- Outbound text uses Telegram-safe HTML rendering (bold, italic, strikethrough, code, links)
- Markdown input is automatically converted; raw HTML from models is escaped
- Audio distinguishes between voice notes and file attachments
- Static stickers (WEBP) are processed through vision with description caching

### Advanced Features

- Draft streaming in private chats with forum topics enabled
- Inline keyboard buttons with callback data support
- Reaction notifications and agent-initiated reactions
- Forum topic threading with isolated configuration per thread

## Group Configuration

By default, bots only respond to direct mentions. Configure group behavior through `channels.telegram.groups`:

```json5
// Allowlist all groups with always-respond mode:
{
  "groups": { "*": { "requireMention": false } }
}
```

**Important:** Setting `channels.telegram.groups` creates an allowlist - only listed groups or wildcard entries are accepted.

### Two-Level Access Control

- **Group allowlist** via configuration (which groups are permitted)
- **Sender filtering** via `groupPolicy` (open, allowlist, or disabled)

## Privacy & Permissions

Telegram's default Privacy Mode restricts message visibility. To receive all group messages, either:

- Disable privacy mode via `/setprivacy` at BotFather (then remove/re-add bot to groups)
- Promote the bot to group admin status

## Limitations

- Outbound text is chunked to `channels.telegram.textChunkLimit` (default 4000) with optional paragraph-boundary splitting via `chunkMode="newline"`
- Media uploads/downloads cap at `mediaMaxMb` (default 5MB)
- Telegram Bot API does not support read receipts

## Troubleshooting

Common issues stem from:

- IPv6 routing failures to `api.telegram.org` (force IPv4 or enable IPv6 egress)
- Privacy Mode preventing group visibility (confirm via `/setprivacy`)
- Missing group allowlist entries when `channels.telegram.groups` is configured
- Authorization failures for command execution (pairing or `allowFrom` required)