Telegram Channel - IronClaw

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

Message @BotFather on Telegram
Send /newbot and follow the prompts
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

Unknown user sends a message to your bot
Bot replies: To pair with this bot, run: ironclaw pairing approve telegram ABC12345
You run: ironclaw pairing approve telegram ABC12345
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

Add your bot to a group
Set bot_username in config (e.g., "MyIronClawBot")
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:

Start tunnel: ngrok http 8080
Set TUNNEL_URL=https://abc123.ngrok-free.app
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?

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

Documentation Index

​Features

​Prerequisites

​Quick Start

​1. Create a Bot

​2. Configure via Setup Wizard

​3. (Optional) Configure Tunnel for Webhooks

​Configuration

​Configuration Options

​DM Pairing

​Flow

​Commands

​Group Chat

​Mention Triggering

​Configuration

​Webhook vs Polling

​Webhook Mode (Recommended)

​Polling Mode

​Secrets

​Webhook Secret (Optional)

​Commands

​Markdown Formatting

​Manual Installation

​Troubleshooting

​Messages not delivered

​Pairing code not received

​Group mentions not working

​”Connection refused” when starting

​Rate limit errors

​Source Code

​Example Usage

​Simple DM

​Group Chat

​Pairing Flow

Build docs developers (and LLMs) love

Features

Prerequisites

Quick Start

1. Create a Bot

2. Configure via Setup Wizard

3. (Optional) Configure Tunnel for Webhooks

Configuration

Configuration Options

DM Pairing

Flow

Commands

Group Chat

Mention Triggering

Configuration

Webhook vs Polling

Webhook Mode (Recommended)

Polling Mode

Secrets

Webhook Secret (Optional)

Commands

Markdown Formatting

Manual Installation

Troubleshooting

Messages not delivered

Pairing code not received

Group mentions not working

”Connection refused” when starting

Rate limit errors

Source Code

Example Usage

Simple DM

Group Chat

Pairing Flow