# Telegram Channel Setup

This guide covers configuring the Telegram channel for OptimClaw, including DM pairing for access control.

## Overview

The Telegram channel lets you interact with OptimClaw via Telegram DMs and groups. It supports:

- **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

## Prerequisites

- OptimClaw installed and configured (`optimclaw 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
optimclaw 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
# 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).

## DM Pairing

When an unknown user DMs your bot, they receive a pairing code. You must approve them before they can message the agent.

### Flow

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

### Commands

```bash
# List pending pairing requests
optimclaw pairing list telegram

# List as JSON
optimclaw pairing list telegram --json

# Approve a user by code
optimclaw pairing approve telegram ABC12345
```

### Configuration

Edit `~/.optimclaw/channels/telegram.capabilities.json` (or the config injected by the host):

| Option | Values | Default | Description |
|--------|--------|---------|-------------|
| `dm_policy` | `open`, `allowlist`, `pairing` | `pairing` | `open` = allow all; `allowlist` = config + approved only; `pairing` = allowlist + send pairing reply to unknown |
| `allow_from` | `["user_id", "username", "*"]` | `[]` | Pre-approved IDs/usernames. `*` allows everyone. |
| `owner_id` | Telegram user ID | `null` | When set, only this user can message (overrides dm_policy) |
| `bot_username` | Bot username (no @) | `null` | Used for mention detection in groups; when set, only strips this mention from messages |
| `respond_to_all_group_messages` | `true`/`false` | `false` | When true, respond to all group messages; when false, only @mentions and /commands |

## Manual Installation

If the channel isn't installed via the wizard:

```bash
# Build the Telegram channel (requires wasm32-wasip2 target)
rustup target add wasm32-wasip2
./channels-src/telegram/build.sh

# Install
mkdir -p ~/.optimclaw/channels
cp channels-src/telegram/telegram.wasm channels-src/telegram/telegram.capabilities.json ~/.optimclaw/channels/
```

## 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**: `optimclaw` 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.

## Troubleshooting

### Messages not delivered

- **Polling mode**: Check logs for `getUpdates` errors. Ensure the bot token is valid.
- **Webhook mode**: Verify tunnel is running and `TUNNEL_URL` is correct. Telegram requires HTTPS.

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

### Group mentions not working

- Set `bot_username` in config to your bot's username (e.g., `MyOptimClawBot`)
- Ensure the message contains `@YourBot` or starts with `/`

### "Connection refused" when starting

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