telegram-bot-manager – OpenClaw Skill

---

name: telegram-bot-manager description: Manage and configure Telegram bots for OpenClaw. Use when setting up Telegram integrations, troubleshooting bot connectivity, configuring bot tokens, or managing Telegram channel/webhook settings. Handles bot registration, token validation, and network connectivity checks for api.telegram.org.

Telegram Bot Manager

Quick Start

Setup a new Telegram bot

1. Create bot via BotFather

   • Message @BotFather on Telegram
   • Use /newbot command
   • Follow prompts for bot name and username
   • Copy the bot token (format: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Configure in OpenClaw

   • Add token to OpenClaw config
   • Enable Telegram plugin
   • Set up pairing mode for DM access

Validate bot configuration

# Test Telegram API connectivity
curl -I https://api.telegram.org

# Check bot token validity
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

Common Workflows

Troubleshooting connectivity issues

When api.telegram.org is unreachable:

1. Check network access

   curl -I -m 10 https://api.telegram.org
   

2. Verify DNS resolution

   nslookup api.telegram.org
   

3. Test alternative endpoints

   curl -I https://telegram.org
   

Configuring OpenClaw Telegram integration

See OPENCLAW_CONFIG.md for detailed configuration steps.

Bot token security

• Never commit bot tokens to version control
• Store tokens in environment variables or secure config files
• Rotate tokens if compromised
• Use different tokens for different environments (dev/prod)

Bot Commands Reference

Common Telegram bot commands for BotFather:

• /newbot - Create a new bot
• /mybots - Manage your bots
• /setdescription - Set bot description
• /setabouttext - Set about text
• /setuserpic - Set bot profile picture
• /setcommands - Set bot commands
• /token - Generate new token
• /revoke - Revoke current token
• /setprivacy - Configure privacy mode

Webhook vs Polling

Webhook (Recommended for production)

• Bot receives updates via HTTP POST
• Requires public HTTPS endpoint
• More efficient for high-volume bots

Polling (Good for development)

• Bot continuously checks for updates
• Simpler setup, no public endpoint needed
• Easier to debug locally

See WEBHOOK_SETUP.md for webhook configuration.

Error Handling

Common errors and solutions

"Connection timed out"

• Check firewall rules
• Verify proxy configuration
• Test with different network

"Invalid token"

• Verify token format (should contain colon)
• Check for extra spaces or characters
• Regenerate token if needed

"Bot not responding"

• Verify bot is not blocked
• Check bot privacy settings
• Ensure bot has proper permissions

Testing Your Bot

Manual testing

1. Search for your bot username on Telegram
2. Start a conversation with /start
3. Test basic commands

Automated testing

Use the test script in scripts/test_bot.py for automated validation.

References

• Telegram Bot API Documentation
• BotFather Documentation
• OpenClaw Configuration Guide

Telegram Bot Manager Skill

A comprehensive skill for managing Telegram bots in OpenClaw. This skill provides tools, scripts, and documentation for setting up, configuring, and troubleshooting Telegram bot integrations.

Features

• Bot Setup Automation: Scripts to automate bot configuration
• Connectivity Testing: Tools to test Telegram API access
• Webhook Management: Complete guide for webhook setup
• Troubleshooting: Common issues and solutions
• Security Best Practices: Token management and security guidelines

Quick Start

1. Install the Skill

clawhub install telegram-bot-manager

2. Get Bot Token

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the prompts to create your bot
4. Copy the bot token

3. Run Setup

python3 telegram-bot-manager/scripts/setup_bot.py

Or manually:

export TELEGRAM_BOT_TOKEN="your-bot-token"
python3 telegram-bot-manager/scripts/setup_bot.py

4. Test Your Bot

python3 telegram-bot-manager/scripts/test_bot.py

Skill Contents

Scripts

• setup_bot.py: Automated bot setup and configuration
• test_bot.py: Comprehensive bot testing and validation
• package_skill.py: Package skill for ClawHub distribution

References

• OPENCLAW_CONFIG.md: Detailed OpenClaw configuration guide
• WEBHOOK_SETUP.md: Complete webhook setup instructions

Usage Examples

Basic Bot Setup

# Run the setup wizard
python3 telegram-bot-manager/scripts/setup_bot.py

# Follow the prompts to enter your bot token
# The script will configure OpenClaw automatically

Testing Connectivity

# Test with environment variable
export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
python3 telegram-bot-manager/scripts/test_bot.py

# Or pass token directly
python3 telegram-bot-manager/scripts/test_bot.py "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"

Manual Configuration

Edit your OpenClaw config:

{
  "telegram": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "pairing": true,
    "streamMode": "partial"
  }
}

Then restart:

openclaw gateway restart

Troubleshooting

Network Issues

If you can't access api.telegram.org:

# Test connectivity
curl -I https://api.telegram.org

# Check DNS
nslookup api.telegram.org

# Test with timeout
curl -I -m 10 https://api.telegram.org

See WEBHOOK_SETUP.md for network troubleshooting.

Configuration Issues

Bot not responding:

• Verify token is correct (no extra spaces)
• Check if bot is enabled in config
• Restart OpenClaw gateway

Pairing issues:

• Ensure pairing: true in config
• Check bot privacy settings
• Verify bot is not blocked

Token Management

To rotate token:

1. Get new token from BotFather (/token command)
2. Update OpenClaw config
3. Restart gateway

To revoke token:

1. Use /revoke command in BotFather
2. Update config with new token if needed

Security Best Practices

1. Never commit tokens to version control

   • Use environment variables
   • Store in secure config files

2. Use different tokens for different environments

   • Development: @your_bot_dev
   • Production: @your_bot_prod

3. Regular token rotation

   • Rotate tokens every 3-6 months
   • Revoke immediately if compromised

4. Monitor bot activity

   • Check logs for unusual patterns
   • Review bot usage statistics

Webhook vs Polling

Polling (Default)

• Simpler setup
• Good for development
• No public endpoint needed

Webhook (Production)

• More efficient
• Requires public HTTPS
• Better for high-volume bots

See WEBHOOK_SETUP.md for webhook configuration.

Bot Commands Reference

Common commands for BotFather:

• /newbot - Create new bot
• /mybots - Manage your bots
• /token - Get new token
• /revoke - Revoke current token
• /setdescription - Set bot description
• /setcommands - Set bot commands

Testing

Manual Testing

1. Search for your bot in Telegram
2. Send /start to begin conversation
3. Test basic commands

Automated Testing

python3 telegram-bot-manager/scripts/test_bot.py

Publishing to ClawHub

To publish this skill to ClawHub:

# Package the skill
python3 telegram-bot-manager/scripts/package_skill.py ./telegram-bot-manager

# Login to ClawHub
clawhub login

# Publish
clawhub publish ./telegram-bot-manager \
  --slug telegram-bot-manager \
  --name "Telegram Bot Manager" \
  --version 1.0.0 \
  --changelog "Initial release"

Requirements

• OpenClaw Gateway running
• Telegram Bot Token from BotFather
• Network access to api.telegram.org
• Python 3.6+ (for scripts)

License

This skill is provided as-is for use with OpenClaw.

Support

For issues and questions:

• Check the references folder for detailed guides
• Review Telegram Bot API documentation
• Consult OpenClaw documentation