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

1. Create Bot with BotFather

   Open @BotFather in Telegram and send /newbot. Follow prompts to get your bot token.

2. Get Your User ID

   Message @userinfobot to find your numeric user ID (e.g., 123456789).

3. Configure NullClaw

   Run nullclaw onboard --interactive and select Telegram when prompted, or edit config manually.

4. Start Bot

   Launch with nullclaw gateway or nullclaw channel start telegram.

Configuration

Basic Setup

Edit ~/.nullclaw/config.json:

config.json

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
          "allow_from": ["your_telegram_username"]
        }
      }
    }
  }
}

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

Complete Configuration

config.json

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

"bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

How to get bot token

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Choose a name (display name)
4. Choose a username (must end in bot)
5. Copy the token provided

allow_from (required)

Usernames or user IDs allowed to message your bot:

Specific Users

"allow_from": ["alice", "bob"]

Only @alice and @bob can message the bot.

Allow All

"allow_from": ["*"]

Anyone can message the bot (use with caution).

Numeric IDs

"allow_from": ["123456789", "987654321"]

Use numeric user IDs for more precision.

reply_in_private

Control where the bot replies:

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

"proxy": "socks5://127.0.0.1:1080"

Supported formats:

• socks5://host:port
• socks5://user:pass@host:port

Multiple Accounts

Run multiple Telegram bots simultaneously:

config.json

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

Images

Send photos for vision model analysis

Documents

Attach files for processing

Audio

Voice messages (transcribed via Whisper)

Video

Video files and messages

Voice Message Transcription

Enable audio transcription:

config.json

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

nullclaw gateway

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

Standalone Channel

Run only Telegram channel:

nullclaw channel start telegram

Background Service

Install as system service:

# 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

Use Allowlists

Always specify allow_from to prevent unauthorized access:

"allow_from": ["your_username"]

Never use ["*"] in production.

Encrypt Bot Token

Enable secret encryption:

{
  "secrets": {
    "encrypt": true
  }
}

Tokens are encrypted with ChaCha20-Poly1305.

Use Pairing

Keep gateway pairing enabled:

{
  "gateway": {
    "require_pairing": true
  }
}

Limit Actions

Restrict autonomy level:

{
  "autonomy": {
    "level": "supervised",
    "max_actions_per_hour": 20
  }
}

Troubleshooting

Bot Not Responding

1. Check Bot Token

   Verify token is correct and bot is active via BotFather

2. Check Allowlist

   Ensure your username is in allow_from

3. Check Logs

   Run nullclaw gateway in foreground to see errors

4. Test Connection

   Check if Telegram API is reachable (use proxy if needed)

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:

"proxy": "socks5://127.0.0.1:1080"

Test proxy separately:

curl -x socks5://127.0.0.1:1080 https://api.telegram.org

Advanced Configuration

Group Chat Handling

For group chats, configure reply behavior:

config.json

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

Discord Setup

Configure Discord bot

Memory Backend

Set up vector search