Skip to main content

​
Overview

Channels allow your agent to communicate through various platforms. BabyClaw currently supports Telegram, with more channels coming soon.

​
Channel Configuration

Channels are configured in the channels section of your config file: 
{
  "channels": {
    "telegram": {
      "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

​
Telegram

​
channels.telegram
object
Telegram bot configuration.
​
channels.telegram.botToken
string
required
Bot token from @BotFather. Must not be empty or "REPLACE_ME".

​
Creating a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot to start the creation process
  3. Choose a name for your bot (e.g., “My BabyClaw Bot”)
  4. Choose a username ending in “bot” (e.g., mybabyclaw_bot)
  5. Copy the bot token - it looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

​
Configuration Example

{
  "version": 1,
  "channels": {
    "telegram": {
      "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  },
  "ai": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxxxxxxxxxxxx"
      }
    },
    "models": {
      "chat": "anthropic:claude-sonnet-4-20250514"
    }
  }
}

​
Starting Your Bot

After configuring the bot token:
  1. Start BabyClaw - it will automatically connect to Telegram
  2. Find your bot in Telegram by searching for its username
  3. Send /start to begin chatting

​
Bot Commands

Your Telegram bot automatically supports:
  • /start - Initialize conversation with the bot
  • /help - Show available commands
  • Regular messages for natural conversation

​
Features

Text Messages
  • Send and receive text messages
  • Markdown formatting support
  • Multi-line messages
Media Support
  • Send and receive images
  • Image analysis with vision models
  • Document attachments
Interactive Features
  • Real-time typing indicators
  • Message reactions
  • Reply threading
Group Chats
  • Add bot to group chats
  • Responds when mentioned
  • Configurable participation level
In group chats, the bot follows guidelines from SOUL.md and AGENTS.md about when to speak vs. stay silent.

​
Privacy and Security

Bot Security:
  • Keep your bot token secret
  • Never commit it to version control
  • Regenerate token if compromised (via @BotFather)
User Privacy:
  • Bot can only see messages sent to it or where it’s mentioned
  • Private chats are 1-on-1 between user and bot
  • Group chat behavior follows privacy boundaries

​
Customizing Bot Behavior

Control how your bot behaves in Telegram: In SOUL.md: 
## Group Chat Behavior

In Telegram groups:
- Only respond when directly mentioned or asked a question
- Use reactions for acknowledgment instead of replies
- Stay silent during casual banter
- Be helpful without dominating the conversation
Platform-specific formatting:
  • No markdown tables (use bullet lists)
  • Wrap multiple links in <> to suppress embeds: <https://example.com>
  • Use emoji reactions for lightweight acknowledgment

​
Troubleshooting

Bot doesn’t respond:
  • Verify bot token is correct
  • Check BabyClaw logs for connection errors
  • Ensure bot isn’t blocked by user
  • Try /start command to initialize
Bot responds slowly:
  • Check AI provider API status
  • Verify network connectivity
  • Consider using a faster model
Bot won’t join group:
  • Check bot privacy settings in @BotFather
  • Ensure group allows bots
  • Verify bot has necessary permissions
Configuration errors: 
Invalid configuration: required secret values are missing for channels.telegram.botToken
  • Ensure botToken is set and not "REPLACE_ME"
  • Verify JSON syntax is correct

​
Advanced Configuration

For more control over bot behavior: 
{
  "channels": {
    "telegram": {
      "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  },
  "session": {
    "replyChainMode": "reply-chain"
  }
}
Reply chain mode:
  • default - Standard threading
  • reply-chain - Follow conversation threads more closely

​
Bot Profile Setup

Customize your bot’s profile via @BotFather:
  1. Send /setdescription - Set bot description
  2. Send /setabouttext - Set about text
  3. Send /setuserpic - Upload profile picture
  4. Send /setcommands - Configure command list
Recommended commands: 
start - Start conversation with the bot
help - Show available commands

​
Rate Limits

Telegram enforces rate limits:
  • Messages: ~30 messages/second to different users
  • Group messages: ~20 messages/minute per group
  • Bulk messages: Lower limits for broadcasts
BabyClaw handles rate limiting automatically, but be aware of limits for high-volume usage.

​
Legacy Configuration

Older versions used a different structure: 
{
  "telegram": {
    "botToken": "..."
  }
}
This is automatically migrated to: 
{
  "channels": {
    "telegram": {
      "botToken": "..."
    }
  }
}
Both formats work, but the channels format is recommended.

​
Future Channels

Planned channel support:
  • WhatsApp (via QR code linking)
  • Discord
  • Slack
  • SMS
  • Web interface
Channel configuration will follow the same structure: 
{
  "channels": {
    "telegram": { "botToken": "..." },
    "discord": { "botToken": "..." },
    "whatsapp": { "linked": true }
  }
}

​
Best Practices

  1. Secure your tokens - Never expose bot tokens publicly
  2. Set bot profile - Add description and profile picture
  3. Configure commands - Help users discover bot features
  4. Test in private - Test bot behavior before adding to groups
  5. Monitor logs - Watch for errors or unexpected behavior
  6. Customize behavior - Use SOUL.md to define channel-specific rules

​
Multi-Channel Usage

You can run multiple channels simultaneously: 
{
  "channels": {
    "telegram": {
      "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}
Each channel maintains its own session history but shares the same workspace and memory.
Running the same bot token on multiple BabyClaw instances will cause conflicts. Use one instance per bot.

Build docs developers (and LLMs) love

Get started for freeTalk to us