Telegram Channel

Setup and usage guide for the Telegram Bot API channel

The Telegram channel lets you interact with IronClaw via Telegram DMs and groups.

Features

• Webhook mode (recommended) - Instant delivery via tunnel
• Polling mode - No tunnel required, ~30s delay
• DM pairing - Approve unknown users before they can message the agent
• Group mentions - @YourBot or /command to trigger in groups
• Markdown formatting - Rich text responses
• Thread continuity - Conversation history persists across restarts

Prerequisites

• IronClaw installed and configured (ironclaw onboard)
• A Telegram bot token from @BotFather

Quick Start

1. Create a Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Configure via Setup Wizard

ironclaw onboard

When prompted, enable the Telegram channel and paste your bot token. The wizard will:

• Validate the token
• Optionally configure a webhook secret
• Set up tunnel (if you want webhook mode)

3. (Optional) Configure Tunnel for Webhooks

For instant message delivery, expose your agent via a tunnel:

# ngrok
ngrok http 8080

# Cloudflare
cloudflared tunnel --url http://localhost:8080

Set the tunnel URL in settings or via TUNNEL_URL env var. Without a tunnel, the channel uses polling (~30s delay).

Configuration

Edit ~/.ironclaw/channels/telegram.capabilities.json:

{
  "config": {
    "bot_username": null,
    "owner_id": null,
    "dm_policy": "pairing",
    "allow_from": [],
    "respond_to_all_group_messages": false
  }
}

Configuration Options

Option	Type	Default	Description
bot_username	string	null	Bot username (no @) for mention detection in groups
owner_id	integer	null	Telegram user ID; when set, only this user can message
dm_policy	string	"pairing"	open, allowlist, or pairing
allow_from	array	[]	Pre-approved user IDs/usernames. ["*"] allows everyone
respond_to_all_group_messages	boolean	false	When true, respond to all group messages; when false, only @mentions and /commands

DM Pairing

When an unknown user DMs your bot, they receive a pairing code:

Flow

1. Unknown user sends a message to your bot
2. Bot replies: To pair with this bot, run: ironclaw pairing approve telegram ABC12345
3. You run: ironclaw pairing approve telegram ABC12345
4. User is added to the allow list; future messages are delivered

Commands

# List pending pairing requests
ironclaw pairing list telegram

# List as JSON
ironclaw pairing list telegram --json

# Approve a user by code
ironclaw pairing approve telegram ABC12345

Group Chat

Mention Triggering

By default, the bot only responds to:

• @mentions - @YourBot what's the weather?
• Commands - /help or /start

Set respond_to_all_group_messages: true to respond to every message in approved groups.

Configuration

1. Add your bot to a group
2. Set bot_username in config (e.g., "MyIronClawBot")
3. Messages with @MyIronClawBot will be forwarded to the agent

Example:

{
  "config": {
    "bot_username": "MyIronClawBot",
    "respond_to_all_group_messages": false
  }
}

Now @MyIronClawBot hello triggers the agent, but hello (without mention) is ignored.

Webhook vs Polling

Webhook Mode (Recommended)

Pros:

• Instant message delivery
• Lower server load
• More reliable

Cons:

• Requires public HTTPS URL (tunnel)
• Tunnel must stay running

Setup:

1. Start tunnel: ngrok http 8080
2. Set TUNNEL_URL=https://abc123.ngrok-free.app
3. The channel registers webhook at /webhook/telegram

Polling Mode

Pros:

• No tunnel required
• Works behind firewall/NAT

Cons:

• ~30s delay for messages
• Higher API usage (getUpdates every 30s)

Setup:

Don’t set TUNNEL_URL. The channel automatically uses polling.

Secrets

The channel expects a secret named telegram_bot_token. Configure via:

• Setup wizard - Saves to encrypted secrets store
• Environment - TELEGRAM_BOT_TOKEN=your_token
• Secrets store - ironclaw CLI (if available)

Webhook Secret (Optional)

For webhook validation, set telegram_webhook_secret in secrets. Telegram will send X-Telegram-Bot-Api-Secret-Token with each request; the host validates it before forwarding.

export TELEGRAM_WEBHOOK_SECRET=my-secure-secret

Commands

Telegram commands are processed by the agent’s submission parser:

Command	Description
/start	Greet the user (emits [User started the bot])
/interrupt	Stop current task
/stop	Same as /interrupt
/help	Show available commands
/undo	Undo last action
/redo	Redo undone action
/ping	Check if agent is responsive
/tools	List available tools
/version	Show IronClaw version

Commands with arguments are stripped of the command prefix and passed as user input.

Example:

• /help → Agent shows help
• /help me fix this bug → Agent receives "me fix this bug"

Markdown Formatting

Responses are sent with Telegram’s Markdown parser. If parsing fails (e.g., unescaped underscores in tool output), the channel retries as plain text.

Supported syntax:

• *bold*
• _italic_
• `code`
• code block
• [link](url)

Manual Installation

If the channel isn’t installed via the wizard:

# Build the Telegram channel (requires wasm32-wasip2 target)
rustup target add wasm32-wasip2
cd ~/workspace/source/channels-src/telegram
./build.sh

# Install
mkdir -p ~/.ironclaw/channels
cp telegram.wasm telegram.capabilities.json ~/.ironclaw/channels/

Troubleshooting

Messages not delivered

Polling mode:

• Check logs for getUpdates errors
• Ensure the bot token is valid
• Verify webhook is deleted (polling doesn’t work with active webhook)

Webhook mode:

• Verify tunnel is running and TUNNEL_URL is correct
• Telegram requires HTTPS (ngrok/Cloudflare provide this)
• Check webhook status: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Pairing code not received

• Verify the channel can send messages (HTTP allowlist includes api.telegram.org)
• Check dm_policy is pairing (not allowlist which blocks without reply)
• Check logs for “Failed to send pairing reply”

Group mentions not working

• Set bot_username in config to your bot’s username (e.g., MyIronClawBot)
• Ensure the message contains @YourBot or starts with /
• Verify the bot is a member of the group

”Connection refused” when starting

• For webhook mode: Start your tunnel before ironclaw run
• For polling only: No tunnel needed; ignore tunnel-related warnings

Rate limit errors

• Telegram’s Bot API has a limit of ~30 messages/second
• The channel enforces 30 requests/minute for safety
• If you hit this, reduce message frequency or batch responses

Source Code

• Implementation: ~/workspace/source/channels-src/telegram/src/lib.rs
• Capabilities: ~/workspace/source/channels-src/telegram/telegram.capabilities.json
• Docs: ~/workspace/source/docs/TELEGRAM_SETUP.md

Example Usage

Simple DM

You: Hello!
Bot: Hi! I'm your IronClaw agent. How can I help?

You: What's the weather in Tokyo?
Bot: Let me check that for you...
     [Tool execution: weather_api]
     The current weather in Tokyo is 22°C, partly cloudy.

Group Chat

Alice: @MyIronClawBot summarize this conversation
Bot: [reads chat history]
     Here's a summary of the last 10 messages...

Bob: /help
Bot: Available commands:
     /interrupt - Stop current task
     /tools - List available tools
     ...

Pairing Flow

Unknown User: Hello
Bot: To pair with this bot, run: ironclaw pairing approve telegram ABC12345

[You run: ironclaw pairing approve telegram ABC12345]

Unknown User: Hello
Bot: Hi! I'm your IronClaw agent. How can I help?