Telegram Setup

New to channel setup? For a hands-on, step-by-step tutorial, check out our Channel Setup Tutorial. This page is a comprehensive reference covering all Telegram features and configuration options.

Telegram is a popular messaging platform with excellent bot support. OpenClaw (formerly Moltbot, Clawdbot) connects to Telegram using the Bot API via grammY, providing DMs, groups, and rich media support.

Setting up Telegram requires creating a bot with BotFather:

1. Create bot with @BotFather
2. Get your bot token
3. Configure in Moltbot
4. Start chatting!

Step 1: Talk to BotFather

1. Open Telegram
2. Search for @BotFather
3. Start a chat

Step 2: Create Bot

1. Send: /newbot
2. Choose a name for your bot
3. Choose a username (must end in 'bot')
4. Copy the bot token

Step 3: Configure Bot

Optional: Set bot description and commands:

• /setdescription - Set bot description
• /setcommands - Set bot commands

Basic Configuration

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE"
    }
  }
}

Setting Token

Add your bot token:

1. Get token from BotFather
2. Add to configuration file
3. Or set via environment variable: TELEGRAM_BOT_TOKEN

Direct Messages

• Send and receive DMs
• Rich media support
• Voice notes
• Location sharing
• Reply threading

Group Chats

• Join group chats
• Mention-based activation (default)
• Group allowlists
• Reply tags
• Photo albums

Media Support

• Images and photos
• Audio and voice notes
• Video files
• Documents
• Stickers
• Location sharing

DM Allowlist

{
  "channels": {
    "telegram": {
      "allowFrom": ["@username", "123456789"]
    }
  }
}

Group Configuration

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-1001234567890": {
          "requireMention": false,
          "activation": "always"
        }
      }
    }
  }
}

DM Pairing

By default, unknown senders require pairing:

• Unknown contacts receive a pairing code
• Approve with: openclaw pairing approve telegram <code>
• Once approved, added to allowlist

Bot Token Security

Keep your bot token secure:

• Never share your token
• Store in configuration file (not in code)
• Use environment variables if needed
• Regenerate token if compromised

Bot Not Responding

If bot doesn't respond:

1. Verify bot token is correct
2. Check Gateway is running
3. Check bot is enabled in config
4. Review Gateway logs

Can't Receive Messages

If messages aren't received:

1. Check allowlist configuration
2. Verify pairing if required
3. Check bot permissions
4. Ensure bot is added to groups

Group Issues

If group features don't work:

1. Ensure bot is added to group
2. Check group allowlist
3. Verify mention patterns
4. Check group ID format

• Use Allowlists - Control who can message you
• Enable Mention Gating - For group chats
• Secure Token - Keep bot token private
• Monitor Logs - Check for issues
• Test Thoroughly - Test in DMs before groups