Introduction
# Telegram Bot Builder Skill
Build and manage Telegram bots directly from Clawdbot.
## Setup
1. Open Telegram and message [@BotFather](https://t.me/BotFather) 2. Send `/newbot` and follow the prompts to create your bot 3. Copy the bot token (looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`) 4. Set environment variable: ```bash export TELEGRAM_BOT_TOKEN="your-bot-token" ```
## API Base URL
All requests go to: ``` https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/METHOD_NAME ```
## Usage
### Bot Information
#### Get bot info ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe" | jq ```
#### Get bot commands ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMyCommands" | jq ```
#### Set bot commands ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setMyCommands" \ -H "Content-Type: application/json" \ -d '{ "commands": [ {"command": "start", "description": "Start the bot"}, {"command": "help", "description": "Show help message"}, {"command": "settings", "description": "Bot settings"} ] }' | jq ```
### Sending Messages
#### Send text message ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "text": "Hello from Clawdbot!", "parse_mode": "HTML" }' | jq ```
#### Send message with inline keyboard ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "text": "Choose an option:", "reply_markup": { "inline_keyboard": [ [{"text": "Option 1", "callback_data": "opt1"}, {"text": "Option 2", "callback_data": "opt2"}], [{"text": "Visit Website", "url": "https://example.com"}] ] } }' | jq ```
#### Send message with reply keyboard ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "text": "Choose from keyboard:", "reply_markup": { "keyboard": [ [{"text": "Button 1"}, {"text": "Button 2"}], [{"text": "Send Location", "request_location": true}] ], "resize_keyboard": true, "one_time_keyboard": true } }' | jq ```
#### Send photo ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendPhoto" \ -F "chat_id=CHAT_ID" \ -F "photo=@/path/to/image.jpg" \ -F "caption=Photo caption here" | jq ```
#### Send photo by URL ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendPhoto" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "photo": "https://example.com/image.jpg", "caption": "Image from URL" }' | jq ```
#### Send document ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendDocument" \ -F "chat_id=CHAT_ID" \ -F "document=@/path/to/file.pdf" \ -F "caption=Here is your document" | jq ```
#### Send location ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendLocation" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "latitude": 40.7128, "longitude": -74.0060 }' | jq ```
### Getting Updates
#### Get updates (polling) ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates" | jq ```
#### Get updates with offset (mark as read) ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?offset=UPDATE_ID" | jq ```
#### Get updates with timeout (long polling) ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?timeout=30" | jq ```
### Webhooks
#### Set webhook ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhook", "allowed_updates": ["message", "callback_query"] }' | jq ```
#### Get webhook info ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo" | jq ```
#### Delete webhook ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook" | jq ```
### Chat Management
#### Get chat info ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChat?chat_id=CHAT_ID" | jq ```
#### Get chat member count ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChatMemberCount?chat_id=CHAT_ID" | jq ```
#### Get chat administrators ```bash curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChatAdministrators?chat_id=CHAT_ID" | jq ```
#### Ban user from chat ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/banChatMember" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "user_id": USER_ID }' | jq ```
#### Unban user ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/unbanChatMember" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "user_id": USER_ID, "only_if_banned": true }' | jq ```
### Message Management
#### Edit message text ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/editMessageText" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "message_id": MESSAGE_ID, "text": "Updated message text" }' | jq ```
#### Delete message ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "message_id": MESSAGE_ID }' | jq ```
#### Pin message ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/pinChatMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "CHAT_ID", "message_id": MESSAGE_ID }' | jq ```
#### Forward message ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/forwardMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "TARGET_CHAT_ID", "from_chat_id": "SOURCE_CHAT_ID", "message_id": MESSAGE_ID }' | jq ```
### Callback Queries
#### Answer callback query ```bash curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/answerCallbackQuery" \ -H "Content-Type: application/json" \ -d '{ "callback_query_id": "CALLBACK_QUERY_ID", "text": "Button clicked!", "show_alert": false }' | jq ```
## Notes
- **Chat ID**: Can be positive (user) or negative (group/channel). Get it from updates or use @userinfobot - **Parse modes**: `HTML`, `Markdown`, `MarkdownV2` - **Rate limits**: ~30 messages/second to different chats, 1 message/second to same chat - **File limits**: Photos up to 10MB, documents up to 50MB - **Bot permissions**: Bots can't message users first - user must /start the bot
## HTML Formatting
```html <b>bold</b> <i>italic</i> <u>underline</u> <s>strikethrough</s> <code>inline code</code> <pre>code block</pre> <a href="https://example.com">link</a> <tg-spoiler>spoiler</tg-spoiler> ```
## Examples
### Simple echo bot (bash script) ```bash #!/bin/bash OFFSET=0 while true; do UPDATES=$(curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?offset=$OFFSET&timeout=30") for UPDATE in $(echo "$UPDATES" | jq -c '.result[]'); do UPDATE_ID=$(echo "$UPDATE" | jq '.update_id') CHAT_ID=$(echo "$UPDATE" | jq '.message.chat.id') TEXT=$(echo "$UPDATE" | jq -r '.message.text') if [ "$TEXT" != "null" ]; then curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d "{\"chat_id\": $CHAT_ID, \"text\": \"You said: $TEXT\"}" fi OFFSET=$((UPDATE_ID + 1)) done done ```
### Get your chat ID ```bash # 1. Send a message to your bot # 2. Run this to see your chat ID: curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates" | jq '.result[-1].message.chat.id' ```
### Send to channel ```bash # Use @channelname or channel ID (starts with -100) curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d '{ "chat_id": "@your_channel_name", "text": "Channel announcement!" }' | jq ```
## Useful Resources
- [Bot API Documentation](https://core.telegram.org/bots/api) - [BotFather Commands](https://core.telegram.org/bots#botfather) - [Bot API Changelog](https://core.telegram.org/bots/api-changelog)