Telegram - SimpleClaw

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

Create a Telegram Bot

Open Telegram and message @BotFather:

Send /newbot
Choose a name for your bot
Choose a username (must end in bot)
Copy the bot token provided by BotFather

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

Verify Connection

Check that Telegram is running:

simpleclaw channels status telegram

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

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

User sends /start or any message

With dmPolicy: pairing, you approve the user:

simpleclaw pairing approve telegram 123456789

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

Add your bot to a Telegram group
Get the group chat ID (use /status command or check logs)
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:

Bot is added to the group
Group ID is in your groups allowlist (if using groupPolicy: allowlist)
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

Get Started

Core Concepts

Messaging Channels

Features

Platforms

Security

​Features

​Setup

​Configuration

​Basic Configuration

​Environment Variable

​Token File

​Multi-Account Setup

​Security

​DM Policy

​Group Policy

​Pairing Workflow

​Advanced Features

​Webhook Mode

​Proxy Support

​Reply Threading

​Native Commands

​Message Features

​Sending Messages

​Markdown Formatting

​Polls

​Reactions

​Group Management

​Adding Bot to Groups

​Mention Detection

​Group Auditing

​Troubleshooting

​CLI Commands

​API Reference

​Channel ID

​Target ID Format

​Capabilities

​Configuration Schema

​Best Practices

Use Token Files

Enable Pairing

Restrict Groups

Use Webhooks

​Next Steps

Security Guide

Multi-Channel

Build docs developers (and LLMs) love

Features

Setup

Configuration

Basic Configuration

Environment Variable

Token File

Multi-Account Setup

Security

DM Policy

Group Policy

Pairing Workflow

Advanced Features

Webhook Mode

Proxy Support

Reply Threading

Native Commands

Message Features

Sending Messages

Markdown Formatting

Polls

Reactions

Group Management

Adding Bot to Groups

Mention Detection

Group Auditing

Troubleshooting

CLI Commands

API Reference

Channel ID

Target ID Format

Capabilities

Configuration Schema

Best Practices

Next Steps