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:

{
  "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

bot_token · string · required

Telegram bot token from @BotFather

allow_from · 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

reply_in_private · boolean · default: "false"

When true, bot replies to group messages via private DM instead of in the group chat

proxy_url · string · default: "null"

HTTP/SOCKS5 proxy URL for API requests (e.g., "http://proxy.example.com:8080" or "socks5://127.0.0.1:1080")

transcribe_voice · boolean · default: "true"

Automatically transcribe voice messages using the configured speech-to-text provider

account_id · string · default: "default"

Account identifier for multi-account setups

Setup Guide

1. Create a Telegram Bot

   1. Open Telegram and search for @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)
2. 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 to get your ID directly.

3. Configure NullClaw

   Add the bot token and your user ID to ~/.nullclaw/config.json:

   {
     "channels": {
       "telegram": {
         "accounts": {
           "main": {
             "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
             "allow_from": ["YOUR_USER_ID"]
           }
         }
       }
     }
   }
   
4. Start NullClaw

   Run nullclaw and send a message to your bot on Telegram. You should receive a response.

Proxy Configuration

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

HTTP Proxy

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "proxy_url": "http://proxy.example.com:8080"
        }
      }
    }
  }
}

SOCKS5 Proxy

{
  "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:

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:

{
  "reply_in_private": false
}

Private Replies

Enable reply_in_private to have the bot DM responses instead:

{
  "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:

{
  "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