Telegram Channel Setup

​

Features

• Webhook mode (recommended): Instant message 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

​

Prerequisites

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

​

Step 1: Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Choose a name (e.g., “My IronClaw Bot”)
4. Choose a username (e.g., “my_ironclaw_bot”)
5. Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

​

Step 2: Configure via Setup Wizard

ironclaw onboard

1. Enable Telegram channel: Select “Yes”
2. Enter bot token: Paste the token from BotFather
3. Webhook secret: Press Enter to auto-generate (or provide your own)
4. Tunnel URL (optional): If you want webhook mode, configure a tunnel

​

Step 3: Choose Delivery Mode

​

Webhook Mode (Recommended)

# Using ngrok
ngrok http 8080

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

# In .env or environment
export TUNNEL_URL=https://your-subdomain.ngrok.io

# Or in setup wizard
ironclaw onboard

​

Polling Mode

​

Step 4: Test the Bot

1. Open Telegram and search for your bot by username
2. Send a message: “Hello!”
3. Check IronClaw logs for the message
4. The agent should respond

​

DM Pairing

​

How It Works

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 approve: ironclaw pairing approve telegram ABC12345
4. User is added to the allow list; future messages are delivered

​

Pairing 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

# The user can now message your bot

​

Pairing Policies

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

​

Policy Examples

{
  "config": {
    "dm_policy": "open"
  }
}

{
  "config": {
    "dm_policy": "allowlist",
    "allow_from": ["123456789", "@alice", "@bob"]
  }
}

{
  "config": {
    "owner_id": 123456789
  }
}

​

Group Chat

@my_ironclaw_bot What's the weather?

/status
/help

• Set bot_username in config to enable mention detection
• Set respond_to_all_group_messages: true to respond to all messages (not just mentions)

​

Manual Installation

# Add WASM target
rustup target add wasm32-wasip2

# Build Telegram channel
cd channels-src/telegram
cargo build --release --target wasm32-wasip2

# Install
mkdir -p ~/.ironclaw/channels
cp target/wasm32-wasip2/release/telegram.wasm ~/.ironclaw/channels/telegram.wasm
cp telegram.capabilities.json ~/.ironclaw/channels/

​

Secrets

• telegram_bot_token: Required. Your bot token from BotFather.
• telegram_webhook_secret: Optional. Used to validate webhook requests.

1. Setup wizard: ironclaw onboard
2. Environment: export TELEGRAM_BOT_TOKEN=your_token
3. Database: Stored encrypted if using the wizard

​

Webhook Secret

export TELEGRAM_WEBHOOK_SECRET=your_secret_here
ironclaw onboard  # Or add to existing config

​

Troubleshooting

​

Messages Not Delivered

1. Check logs for getUpdates errors
2. Verify bot token: curl https://api.telegram.org/bot<TOKEN>/getMe
3. Ensure IronClaw is running

1. Verify tunnel is running and accessible
2. Check TUNNEL_URL is correct and includes https://
3. Test webhook: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo
4. Telegram requires HTTPS (no self-signed certs)

​

Pairing Code Not Received

1. Verify dm_policy is pairing (not allowlist)
2. Check the channel can send messages (logs should show “Sent pairing message”)
3. Ensure HTTP allowlist includes api.telegram.org in capabilities

​

Group Mentions Not Working

1. Set bot_username in config to your bot’s username (no @)
2. Ensure the message contains @YourBot or starts with /
3. Verify the bot is a member of the group

​

”Connection Refused” on Startup

​

Bot Token Invalid

1. Verify the token format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
2. Check for extra spaces or newlines
3. Get a new token: Message @BotFather and send /token

​

Advanced Configuration

​

Custom Polling Interval

{
  "config": {
    "poll_interval_ms": 10000
  }
}

​

Rate Limits

{
  "capabilities": {
    "http": {
      "rate_limit": {
        "requests_per_minute": 30,
        "requests_per_hour": 1000
      }
    },
    "channel": {
      "emit_rate_limit": {
        "messages_per_minute": 50,
        "messages_per_hour": 3000
      }
    }
  }
}

​

Multiple Bots

# Bot 1
export TELEGRAM_BOT_TOKEN=token1
export DATABASE_URL=postgresql://localhost/ironclaw_bot1
ironclaw run

# Bot 2
export TELEGRAM_BOT_TOKEN=token2
export DATABASE_URL=postgresql://localhost/ironclaw_bot2
ironclaw run

​

Security Considerations

1. Keep bot token secret: Never commit to git or share publicly
2. Use webhook secret: Prevents unauthorized webhook requests
3. Enable DM pairing: Prevents spam and unauthorized access
4. Set owner_id: For maximum security, restrict to a single user
5. Monitor logs: Watch for suspicious activity

​

Next Steps

• Learn about building channels to create your own
• Explore building WASM tools for custom capabilities
• Set up MCP servers for external integrations