Files

Selig 4c966a3ad2 Initial commit: OpenClaw Skill Collection

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.

2026-03-13 10:58:30 +08:00

2.9 KiB

Raw Blame History

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

Create a bot token through @BotFather on Telegram
Configure the token via environment variable (TELEGRAM_BOT_TOKEN) or config file (channels.telegram.botToken)
Start the gateway - Telegram initialization occurs automatically when a valid token resolves
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:

// 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)

2.9 KiB Raw Blame History