Telegram Setup

Overview

Telegram is the recommended channel for Clawdbot. It offers the most stable connection, full feature support, and the easiest setup process.

Why Telegram?

• Official Bot API: No risk of account restrictions
• Rich features: Inline mode, groups, media support
• No phone requirement: Works independently
• Free and unlimited: No message limits

Prerequisites

• Clawdbot installed
• Telegram account

Setup

1. Create a Telegram Bot

   • Open Telegram and search for @BotFather
   • Send /newbot
   • Choose a name (e.g., “My Clawdbot”)
   • Choose a username (must end in bot, e.g., my_clawdbot_bot)
   • Copy the API token provided

2. Configure Clawdbot

   Edit .env:

   TELEGRAM_ENABLED=true
   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

3. Start Clawdbot

   python -m clawdbot

4. Test the Bot

   • Find your bot in Telegram by its username
   • Send /start
   • Send any message

Configuration Options

.env

# Required: Bot token from BotFather
TELEGRAM_BOT_TOKEN=your_token_here

# Enable/disable Telegram channel
TELEGRAM_ENABLED=true

# Rate limiting (messages per minute per user)
TELEGRAM_RATE_LIMIT=20

# Allow group chats
TELEGRAM_GROUPS_ENABLED=true

# Only respond when mentioned in groups
TELEGRAM_GROUP_MENTION_ONLY=true

# Allowed users (comma-separated Telegram user IDs, empty = all)
TELEGRAM_ALLOWED_USERS=123456789,987654321

# Admin users (can use special commands)
TELEGRAM_ADMIN_USERS=123456789

Features

Commands

Built-in commands (customizable):

Command	Description
/start	Begin interaction with the bot
/help	Show available commands
/reset	Clear conversation history
/settings	User settings (if implemented)

Inline Mode

Enable inline queries for quick access from any chat:

1. Configure with @BotFather: /setinline
2. Set placeholder text
3. Users can type @yourbot query in any chat

# In .env
TELEGRAM_INLINE_ENABLED=true

Group Chat Support

Clawdbot works in Telegram groups:

# In .env
TELEGRAM_GROUPS_ENABLED=true

# Only respond when @mentioned
TELEGRAM_GROUP_MENTION_ONLY=true

Tip

In groups, disable privacy mode via @BotFather (/setprivacy → Disable) if you want the bot to see all messages, not just commands and mentions.

Media Support

Media Type	Receive	Send
Text	✅	✅
Images	✅	✅
Voice	✅ (transcribed)	✅ (with TTS)
Documents	✅	✅
Stickers	✅	❌
Location	✅	❌

Keyboard & Buttons

Clawdbot can send interactive elements:

• Inline keyboards
• Reply keyboards
• Custom buttons (via plugins)

Advanced Configuration

Webhook Mode

For production, use webhooks instead of polling:

# In .env
TELEGRAM_WEBHOOK_ENABLED=true
TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook/telegram
TELEGRAM_WEBHOOK_PORT=8443

Multiple Bots

Run multiple Telegram bots from one Clawdbot instance:

TELEGRAM_BOTS=bot1,bot2
TELEGRAM_BOT1_TOKEN=token1
TELEGRAM_BOT2_TOKEN=token2

Custom Commands

Add custom commands via configuration or plugins:

# In a plugin
@clawdbot.command("weather")
async def weather_command(message):
    # Custom implementation
    pass

Troubleshooting

Bot Not Responding

1. Verify token is correct
2. Check logs for errors:

   LOG_LEVEL=DEBUG python -m clawdbot

3. Ensure bot isn’t blocked or deleted
4. Test token with Telegram API directly:

   curl "https://api.telegram.org/bot<TOKEN>/getMe"

“Unauthorized” Error

Your token is invalid. Get a new one from @BotFather.

Bot Works in DM but Not Groups

1. Disable privacy mode: @BotFather → /setprivacy → Disable
2. Or ensure TELEGRAM_GROUP_MENTION_ONLY=true and mention the bot

Rate Limit Errors

Telegram limits are generous, but if hit:

• Reduce TELEGRAM_RATE_LIMIT
• Implement request queuing
• Check for message loops

Messages Delayed

• Check network latency
• Consider webhook mode for faster delivery
• Verify server isn’t overloaded

Security Best Practices

1. Keep token secret: Never commit to version control
2. Restrict users: Set TELEGRAM_ALLOWED_USERS for private bots
3. Use HTTPS: For webhook mode
4. Monitor usage: Watch for abuse in public bots

Example Conversation

User: /start
Bot: Hello! I'm Clawdbot, your AI assistant powered by Claude.
     How can I help you today?

User: Can you explain quantum computing in simple terms?
Bot: Of course! Think of quantum computing like this...

User: /reset
Bot: Conversation cleared. Fresh start! What would you like to discuss?

BotFather Commands Reference

Useful @BotFather commands for customization:

Command	Purpose
/setname	Change bot’s display name
/setdescription	Set bot description
/setabouttext	Set “About” section
/setuserpic	Set bot profile picture
/setcommands	Define command list
/setprivacy	Toggle group privacy mode
/setinline	Enable inline mode

Next Steps

• Add more channels: WhatsApp, Discord
• Explore plugins for extended functionality
• Set up webhooks for production deployment