> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://t.me/BotFather)

## Quick Start

### 1. Create a Bot

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

### 2. Configure via Setup Wizard

```bash theme={null}
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:

```bash theme={null}
# 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`:

```json theme={null}
{
  "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

```bash theme={null}
# 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:**

```json theme={null}
{
  "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.

```bash theme={null}
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:

```bash theme={null}
# 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?
```