Setting up Telegram Bot Integration

Overview

Telegram is one of the most popular messaging platforms for AI bots. This guide shows you how to create a Telegram bot and connect it to your AgentClaw instance.

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a conversation with @BotFather
3. Send the command /newbot
4. Follow the prompts:
   • Choose a display name (e.g., "My AI Assistant")
   • Choose a username ending in "bot" (e.g., "myai_assistant_bot")
5. BotFather will give you an API token - save this!

Example

You: /newbot BotFather: Alright, a new bot. How are we going to call it? You: My AI Assistant BotFather: Good. Now let's choose a username for your bot. You: myai_assistant_bot BotFather: Done! Your token is: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Step 2: Add Bot Token to AgentClaw

1. Go to your AgentClaw instance configuration
2. Add a new environment variable:
   • Name: TELEGRAM_BOT_TOKEN
   • Value: Paste the token from BotFather
3. Save the configuration
4. Start or restart your instance

Step 3: Test Your Bot

1. Wait for your instance to start (check logs)
2. Open Telegram and search for your bot by username
3. Start a conversation with /start
4. Send a message to test the AI response
5. Check AgentClaw logs to see the interaction

Customizing Your Bot

Set Bot Description

1. Message @BotFather
2. Send /setdescription
3. Select your bot
4. Enter a description (shown when users search for your bot)

Set About Text

1. Send /setabouttext to @BotFather
2. Select your bot
3. Enter text (shown in bot's profile)

Set Profile Picture

1. Send /setuserpic to @BotFather
2. Select your bot
3. Upload an image (512x512 recommended)

Set Commands

1. Send /setcommands to @BotFather
2. Select your bot
3. Enter commands in this format:

   start - Start conversation help - Get help clear - Clear conversation history

Bot Privacy Settings

Privacy Mode

By default, bots in groups only receive messages that:

• Start with / (commands)
• Reply to the bot's messages
• @mention the bot

To receive all messages in groups:

1. Send /setprivacy to @BotFather
2. Select your bot
3. Choose "Disable"
4. Bot will now see all group messages

Note: Disabling privacy mode requires group admin permission.

Adding Bot to Groups

1. Create or open a Telegram group
2. Click group settings → Add members
3. Search for your bot by username
4. Add the bot to the group
5. Make bot an admin if needed (for privacy mode disabled)
6. Test with a message: @yourbotname hello

Advanced Features

Inline Mode

Allow users to use your bot in any chat by typing @yourbot query:

1. Send /setinline to @BotFather
2. Select your bot
3. Enter placeholder text
4. OpenClaw will handle inline queries automatically

Bot Payments

Enable payments through your bot:

1. Send /mybots to @BotFather
2. Select your bot → Payments
3. Connect a payment provider
4. Configure in OpenClaw environment variables

Troubleshooting

Bot Not Responding

• Verify TELEGRAM_BOT_TOKEN is correct (no extra spaces)
• Check instance logs for connection errors
• Ensure instance is running (status: Running)
• Try sending /start first to initialize
• Verify bot is not blocked by user

"Bot token invalid" Error

• Get a new token from @BotFather with /token
• Ensure token format is correct: 123456789:ABCdef...
• Check for typos when copying token
• Verify bot wasn't deleted in @BotFather

Bot Receives Messages But Doesn't Reply

• Check AI provider API key is valid
• Verify AI provider has sufficient credits
• Review logs for AI API errors
• See API key errors guide

Bot Not Seeing Group Messages

• Disable privacy mode (see above)
• Make bot a group admin
• Use @mentions to trigger bot

Best Practices

• Choose a clear username: Make it obvious it's a bot
• Set a good description: Explain what your bot does
• Define commands: Help users discover features
• Never share your bot token: Treat it like a password
• Regenerate token if compromised: Use @BotFather's /revoke
• Test before announcing: Ensure bot works properly

Revoking and Regenerating Tokens

If your bot token is compromised:

1. Message @BotFather
2. Send /mybots
3. Select your bot
4. Click "API Token" → "Revoke current token"
5. Get the new token
6. Update TELEGRAM_BOT_TOKEN in AgentClaw
7. Restart your instance

Deleting a Bot

To permanently delete a bot:

1. Message @BotFather
2. Send /deletebot
3. Select the bot to delete
4. Confirm deletion
5. Remove TELEGRAM_BOT_TOKEN from AgentClaw

Warning: This is permanent. The username may become available to others.

Next Steps

• Learn about Discord bot integration
• Explore WhatsApp support
• Read about securing API keys
• Understand monitoring with logs