Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# 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)
|