> ## 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 Bot Setup

> Create and configure a Telegram bot for NullClaw with allowlists and reply policies

Connect NullClaw to Telegram to receive messages and interact with your AI assistant via Telegram's messaging platform.

## Prerequisites

* Telegram account
* BotFather access to create bot tokens
* Your Telegram user ID (numeric)

## Quick Setup

<Steps>
  <Step title="Create Bot with BotFather">
    Open [@BotFather](https://t.me/botfather) in Telegram and send `/newbot`. Follow prompts to get your bot token.
  </Step>

  <Step title="Get Your User ID">
    Message [@userinfobot](https://t.me/userinfobot) to find your numeric user ID (e.g., `123456789`).
  </Step>

  <Step title="Configure NullClaw">
    Run `nullclaw onboard --interactive` and select Telegram when prompted, or edit config manually.
  </Step>

  <Step title="Start Bot">
    Launch with `nullclaw gateway` or `nullclaw channel start telegram`.
  </Step>
</Steps>

## Configuration

### Basic Setup

Edit `~/.nullclaw/config.json`:

```json config.json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
          "allow_from": ["your_telegram_username"]
        }
      }
    }
  }
}
```

<Warning>
  **Security:** Empty `allow_from` denies ALL messages. Use `"*"` to allow everyone (not recommended for production).
</Warning>

### Complete Configuration

```json config.json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
          "allow_from": ["user1", "user2"],
          "reply_in_private": true,
          "proxy": "socks5://127.0.0.1:1080",
          "account_id": "main"
        }
      }
    }
  }
}
```

## Configuration Options

### bot\_token (required)

Your Telegram bot token from BotFather:

```json theme={null}
"bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
```

<Accordion title="How to get bot token">
  1. Open Telegram and search for [@BotFather](https://t.me/botfather)
  2. Send `/newbot` command
  3. Choose a name (display name)
  4. Choose a username (must end in `bot`)
  5. Copy the token provided
</Accordion>

### allow\_from (required)

Usernames or user IDs allowed to message your bot:

<Tabs>
  <Tab title="Specific Users">
    ```json theme={null}
    "allow_from": ["alice", "bob"]
    ```

    Only `@alice` and `@bob` can message the bot.
  </Tab>

  <Tab title="Allow All">
    ```json theme={null}
    "allow_from": ["*"]
    ```

    Anyone can message the bot (use with caution).
  </Tab>

  <Tab title="Numeric IDs">
    ```json theme={null}
    "allow_from": ["123456789", "987654321"]
    ```

    Use numeric user IDs for more precision.
  </Tab>
</Tabs>

### reply\_in\_private

Control where the bot replies:

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

* `true`: Bot replies via DM even if mentioned in groups
* `false`: Bot replies in the same chat where mentioned

### proxy

Optional SOCKS5 proxy for regions where Telegram is blocked:

```json theme={null}
"proxy": "socks5://127.0.0.1:1080"
```

Supported formats:

* `socks5://host:port`
* `socks5://user:pass@host:port`

## Multiple Accounts

Run multiple Telegram bots simultaneously:

```json config.json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "personal": {
          "bot_token": "TOKEN_1",
          "allow_from": ["alice"]
        },
        "work": {
          "bot_token": "TOKEN_2",
          "allow_from": ["bob", "charlie"]
        }
      }
    }
  }
}
```

Each account maintains separate sessions and allowlists.

## Bot Commands

NullClaw registers these commands automatically:

| Command   | Description                  |
| --------- | ---------------------------- |
| `/start`  | Start a conversation         |
| `/new`    | Clear history, start fresh   |
| `/help`   | Show available commands      |
| `/status` | Show model and stats         |
| `/model`  | Switch AI model              |
| `/memory` | Memory tools and diagnostics |
| `/stop`   | Stop active background task  |

Users see these in Telegram's command menu.

## Media Support

Telegram channel supports:

<CardGroup cols={2}>
  <Card title="Images" icon="image">
    Send photos for vision model analysis
  </Card>

  <Card title="Documents" icon="file">
    Attach files for processing
  </Card>

  <Card title="Audio" icon="microphone">
    Voice messages (transcribed via Whisper)
  </Card>

  <Card title="Video" icon="video">
    Video files and messages
  </Card>
</CardGroup>

### Voice Message Transcription

Enable audio transcription:

```json config.json theme={null}
{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "language": "en",
        "models": [
          {
            "provider": "groq",
            "model": "whisper-large-v3"
          }
        ]
      }
    }
  }
}
```

## Running the Bot

### Gateway Mode (Recommended)

Run all channels including Telegram:

```bash theme={null}
nullclaw gateway
```

Access at `http://127.0.0.1:3000` (default).

### Standalone Channel

Run only Telegram channel:

```bash theme={null}
nullclaw channel start telegram
```

### Background Service

Install as system service:

```bash theme={null}
# Install and start
nullclaw service install
nullclaw service start

# Check status
nullclaw service status

# Stop and uninstall
nullclaw service stop
nullclaw service uninstall
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Allowlists">
    Always specify `allow_from` to prevent unauthorized access:

    ```json theme={null}
    "allow_from": ["your_username"]
    ```

    Never use `["*"]` in production.
  </Accordion>

  <Accordion title="Encrypt Bot Token">
    Enable secret encryption:

    ```json theme={null}
    {
      "secrets": {
        "encrypt": true
      }
    }
    ```

    Tokens are encrypted with ChaCha20-Poly1305.
  </Accordion>

  <Accordion title="Use Pairing">
    Keep gateway pairing enabled:

    ```json theme={null}
    {
      "gateway": {
        "require_pairing": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Limit Actions">
    Restrict autonomy level:

    ```json theme={null}
    {
      "autonomy": {
        "level": "supervised",
        "max_actions_per_hour": 20
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Bot Not Responding

<Steps>
  <Step title="Check Bot Token">
    Verify token is correct and bot is active via BotFather
  </Step>

  <Step title="Check Allowlist">
    Ensure your username is in `allow_from`
  </Step>

  <Step title="Check Logs">
    Run `nullclaw gateway` in foreground to see errors
  </Step>

  <Step title="Test Connection">
    Check if Telegram API is reachable (use proxy if needed)
  </Step>
</Steps>

### Messages Ignored

Common causes:

* Username not in `allow_from` (case-sensitive)
* Bot token revoked or expired
* Network/proxy issues
* Rate limiting (too many messages)

### Proxy Not Working

Verify proxy format:

```json theme={null}
"proxy": "socks5://127.0.0.1:1080"
```

Test proxy separately:

```bash theme={null}
curl -x socks5://127.0.0.1:1080 https://api.telegram.org
```

## Advanced Configuration

### Group Chat Handling

For group chats, configure reply behavior:

```json config.json theme={null}
{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "TOKEN",
          "allow_from": ["*"],
          "reply_in_private": false
        }
      }
    }
  }
}
```

* Add bot to group as admin
* Bot responds only when mentioned with `@botname`
* Set `reply_in_private: false` to reply in group

### Rate Limiting

Telegram has built-in rate limits. NullClaw handles:

* Media group coalescing (3-second flush)
* Automatic retry with backoff
* Message splitting at 2000 characters

## Next Steps

<CardGroup cols={2}>
  <Card title="Discord Setup" href="/guides/discord" icon="discord">
    Configure Discord bot
  </Card>

  <Card title="Memory Backend" href="/guides/memory-backends" icon="database">
    Set up vector search
  </Card>
</CardGroup>