Telegram

Connect SimpleClaw to Telegram using the Bot API

SimpleClaw integrates with Telegram through the official Bot API, providing full bot functionality with support for direct messages, groups, channels, and threads.

Features

• Direct messaging and group chats
• Channel posting and thread support
• Media support (images, videos, documents)
• Polls and reactions
• Native bot commands
• Webhook or polling mode
• Markdown formatting

Setup

1. Create a Telegram Bot

   Open Telegram and message @BotFather:

   1. Send /newbot
   2. Choose a name for your bot
   3. Choose a username (must end in bot)
   4. Copy the bot token provided by BotFather
2. Configure SimpleClaw

   Add your bot token to SimpleClaw:

   simpleclaw setup telegram --token "YOUR_BOT_TOKEN"
   

   Or use environment variable:

   export TELEGRAM_BOT_TOKEN="your-token-here"
   simpleclaw setup telegram --use-env
   
3. Verify Connection

   Check that Telegram is running:

   simpleclaw channels status telegram
   

   You should see the bot username and status as “running”.

4. Test the Bot

   Send a message to your bot on Telegram and verify it responds.

Configuration

Basic Configuration

channels:
  telegram:
    enabled: true
    botToken: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

Environment Variable

export TELEGRAM_BOT_TOKEN="your-token-here"

channels:
  telegram:
    enabled: true
    # Token loaded from TELEGRAM_BOT_TOKEN env var

Token File

Store your token in a separate file:

channels:
  telegram:
    enabled: true
    tokenFile: "/path/to/telegram-token.txt"

Multi-Account Setup

channels:
  telegram:
    enabled: true
    accounts:
      personal:
        enabled: true
        name: "Personal Bot"
        botToken: "token-1"
      work:
        enabled: true
        name: "Work Bot"
        botToken: "token-2"

Security

DM Policy

channels:
  telegram:
    dmPolicy: pairing  # Options: open, pairing, allowlist, off
    allowFrom:
      - "123456789"  # Telegram user IDs
      - "user:987654321"

Group Policy

channels:
  telegram:
    groupPolicy: allowlist  # Options: allowlist, open, off
    groups:
      "-1001234567890":  # Group chat ID
        requireMention: true
        toolPolicy: default
        allowFrom:
          - "123456789"  # Additional user restrictions

Pairing Workflow

1. User sends /start or any message
2. With dmPolicy: pairing, you approve the user:
   simpleclaw pairing approve telegram 123456789
   
3. User receives approval notification

Advanced Features

Webhook Mode

Use webhooks instead of polling for better performance:

channels:
  telegram:
    accounts:
      default:
        webhookUrl: "https://your-domain.com/webhook"
        webhookSecret: "your-webhook-secret"
        webhookPath: "/telegram/webhook"
        webhookHost: "0.0.0.0"
        webhookPort: 8443

Proxy Support

channels:
  telegram:
    accounts:
      default:
        proxy: "http://proxy.example.com:8080"

Reply Threading

channels:
  telegram:
    replyToMode: auto  # Options: off, auto, always

Native Commands

Telegram supports bot commands that appear in the UI:

channels:
  telegram:
    # Commands are automatically registered

Set bot commands via BotFather or the API.

Message Features

Sending Messages

# Send text message
simpleclaw message send telegram 123456789 "Hello!"

# Send to group
simpleclaw message send telegram -1001234567890 "Group message"

# Send with media
simpleclaw message send telegram 123456789 "Photo" --media-url "https://example.com/image.jpg"

# Thread reply
simpleclaw message send telegram 123456789 "Reply" --thread-id 42

# Silent notification
simpleclaw message send telegram 123456789 "Quiet message" --silent

Markdown Formatting

Telegram supports Markdown in messages:

*bold text*
_italic text_
[link text](https://example.com)
`inline code`

Polls

Create polls with up to 10 options:

channels:
  telegram:
    # Polls are supported by default

Reactions

React to messages:

channels:
  telegram:
    # Reactions are supported by default

Group Management

Adding Bot to Groups

1. Add your bot to a Telegram group
2. Get the group chat ID (use /status command or check logs)
3. Configure the group in SimpleClaw:

channels:
  telegram:
    groups:
      "-1001234567890":
        requireMention: true

Mention Detection

With requireMention: true, the bot only responds when mentioned:

• @YourBot hello ✓
• hello ✗ (ignored)

Group Auditing

Check if your bot is still in configured groups:

simpleclaw channels status telegram --deep

Troubleshooting

Bot Not Responding

Check the bot token is valid:

simpleclaw channels status telegram --probe

Verify the bot is running:

simpleclaw channels status

Duplicate Token Error

If you see “Duplicate Telegram bot token”, ensure each bot token is only used once:

channels:
  telegram:
    accounts:
      bot1:
        botToken: "unique-token-1"
      bot2:
        botToken: "unique-token-2"  # Must be different

Group Messages Not Received

Ensure:

1. Bot is added to the group
2. Group ID is in your groups allowlist (if using groupPolicy: allowlist)
3. Bot has permission to read messages

# Check group membership
simpleclaw channels status telegram --deep

Webhook Not Working

Verify:

• Webhook URL is publicly accessible
• SSL certificate is valid (required by Telegram)
• Webhook secret matches configuration

Check webhook status:

curl "https://api.telegram.org/bot<token>/getWebhookInfo"

CLI Commands

# Setup
simpleclaw setup telegram --token "YOUR_TOKEN"
simpleclaw setup telegram --use-env
simpleclaw setup telegram --token-file "/path/to/token.txt"

# Status
simpleclaw channels status telegram
simpleclaw channels status telegram --probe
simpleclaw channels status telegram --deep

# Send message
simpleclaw message send telegram <chat-id> <message>

# Pairing
simpleclaw pairing approve telegram 123456789
simpleclaw pairing list telegram

API Reference

Telegram channel implementation: extensions/telegram/src/channel.ts

Channel ID

telegram

Target ID Format

• User DMs: Numeric user ID (e.g., 123456789)
• Groups: Negative chat ID (e.g., -1001234567890)
• Channels: Channel username (e.g., @channelname) or ID

Capabilities

• Chat types: direct, group, channel, thread
• Features: reactions, threads, media, polls, nativeCommands
• Delivery mode: direct
• Text chunk limit: 4000 characters (Markdown)
• Poll max options: 10
• Block streaming: Supported with coalescing

Configuration Schema

See TelegramConfigSchema in source for full schema.

Best Practices

Use Token Files

Store tokens in separate files instead of config:

tokenFile: "/secure/path/token.txt"

Enable Pairing

Use dmPolicy: pairing to control access:

dmPolicy: pairing

Restrict Groups

Use allowlist mode for group access:

groupPolicy: allowlist

Use Webhooks

Webhooks are more efficient than polling for high-traffic bots

Next Steps

Security Guide

Configure DM policies and allowlists

Multi-Channel

Add more messaging platforms