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

# Telegram Channel

> Long-polling Telegram bot integration

The Telegram channel connects NullClaw to Telegram using the Bot API with long-polling for message delivery.

## Features

* Long-polling for real-time message delivery
* Media support (images, documents, video, audio, voice)
* Media groups with automatic batching
* Reply-in-private mode for group chats
* Proxy support (HTTP/SOCKS5)
* Typing indicators
* Voice message transcription
* Interactive buttons (NullClaw interactions)

## Configuration

Add Telegram to your `config.json`:

```json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "YOUR_TELEGRAM_BOT_TOKEN",
          "allow_from": ["123456789", "987654321"],
          "reply_in_private": false,
          "proxy_url": null,
          "transcribe_voice": true
        }
      }
    }
  }
}
```

### Configuration Options

<ParamField path="bot_token" type="string" required>
  Telegram bot token from [@BotFather](https://t.me/BotFather)
</ParamField>

<ParamField path="allow_from" type="string[]" required>
  List of allowed Telegram user IDs. Use `"*"` to allow everyone (not recommended).

  **Finding your user ID**: Send a message to your bot, then check the logs or use [@userinfobot](https://t.me/userinfobot)
</ParamField>

<ParamField path="reply_in_private" type="boolean" default="false">
  When `true`, bot replies to group messages via private DM instead of in the group chat
</ParamField>

<ParamField path="proxy_url" type="string" default="null">
  HTTP/SOCKS5 proxy URL for API requests (e.g., `"http://proxy.example.com:8080"` or `"socks5://127.0.0.1:1080"`)
</ParamField>

<ParamField path="transcribe_voice" type="boolean" default="true">
  Automatically transcribe voice messages using the configured speech-to-text provider
</ParamField>

<ParamField path="account_id" type="string" default="default">
  Account identifier for multi-account setups
</ParamField>

## Setup Guide

<Steps>
  <Step title="Create a Telegram Bot">
    1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
    2. Send `/newbot` and follow the prompts
    3. Choose a name and username for your bot
    4. Copy the bot token (looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)
  </Step>

  <Step title="Get Your User ID">
    1. Send a message to your new bot
    2. Visit `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
    3. Find your user ID in the `from.id` field

    Or use [@userinfobot](https://t.me/userinfobot) to get your ID directly.
  </Step>

  <Step title="Configure NullClaw">
    Add the bot token and your user ID to `~/.nullclaw/config.json`:

    ```json theme={null}
    {
      "channels": {
        "telegram": {
          "accounts": {
            "main": {
              "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
              "allow_from": ["YOUR_USER_ID"]
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Start NullClaw">
    Run `nullclaw` and send a message to your bot on Telegram. You should receive a response.
  </Step>
</Steps>

## Proxy Configuration

If you're in a region where Telegram is restricted, configure a proxy:

### HTTP Proxy

```json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "proxy_url": "http://proxy.example.com:8080"
        }
      }
    }
  }
}
```

### SOCKS5 Proxy

```json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "proxy_url": "socks5://127.0.0.1:1080"
        }
      }
    }
  }
}
```

## Media Support

The Telegram channel supports sending and receiving various media types:

### Supported Media Types

* **Images** (PNG, JPEG, GIF, WebP)
* **Documents** (PDF, TXT, ZIP, etc.)
* **Video** (MP4, MOV, AVI, MKV, WebM)
* **Audio** (MP3, M4A, WAV, FLAC)
* **Voice** (OGG, Opus)

### Sending Media

Use file paths or URLs in your messages:

```markdown theme={null}
Here's the report: /path/to/document.pdf

Check out this image: https://example.com/photo.jpg
```

The channel automatically detects media URLs and file paths, then sends them using the appropriate Telegram API method.

### Media Groups

When multiple images are sent together, they're automatically batched into a media group for better presentation.

## Voice Transcription

When `transcribe_voice` is enabled, voice messages are automatically transcribed using your configured speech-to-text provider. The transcription is included in the message content sent to the agent.

## Group Chat Support

### Standard Group Replies

By default, the bot replies directly in the group:

```json theme={null}
{
  "reply_in_private": false
}
```

### Private Replies

Enable `reply_in_private` to have the bot DM responses instead:

```json theme={null}
{
  "reply_in_private": true
}
```

This is useful for:

* Keeping group chats clean
* Private interactions in public groups
* Sensitive information handling

## Multiple Accounts

You can run multiple Telegram bots simultaneously:

```json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "personal": {
          "bot_token": "TOKEN_1",
          "allow_from": ["YOUR_ID"]
        },
        "work": {
          "bot_token": "TOKEN_2",
          "allow_from": ["TEAM_ID_1", "TEAM_ID_2"]
        },
        "public": {
          "bot_token": "TOKEN_3",
          "allow_from": ["*"],
          "reply_in_private": true
        }
      }
    }
  }
}
```

## Message Limits

Telegram enforces a 4096 character limit per message. NullClaw automatically splits longer messages while respecting UTF-8 character boundaries.

## Bot Commands

The Telegram channel automatically registers these commands with @BotFather:

* `/start` — Start a conversation
* `/new` — Clear history, start fresh
* `/reset` — Alias for /new
* `/help` — Show available commands
* `/status` — Show model and stats
* `/whoami` — Show current session id
* `/model` — Switch model
* `/think` — Set thinking level
* `/verbose` — Set verbose level
* `/exec` — Set execution policy
* `/memory` — Memory tools and diagnostics
* `/stop` — Stop active background task

## Troubleshooting

### Bot Not Responding

1. Verify bot token is correct
2. Check that your user ID is in `allow_from`
3. Ensure NullClaw is running
4. Check logs for errors: `nullclaw --log-level debug`

### Proxy Connection Failed

1. Verify proxy URL format
2. Test proxy with curl: `curl -x "http://proxy:8080" https://api.telegram.org`
3. Check proxy authentication if required

### Media Not Sending

1. Verify file path is absolute or URL is accessible
2. Check file size limits (20MB for photos, 50MB for other media)
3. Ensure file format is supported by Telegram

## Source Code

Implementation: `src/channels/telegram.zig`