All requests go to:

https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/METHOD_NAME

Usage

Bot Information

Get bot info

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe" | jq

Get bot commands

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMyCommands" | jq

Set bot commands

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

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

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

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

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

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

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

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)

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates" | jq

Get updates with offset (mark as read)

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?offset=UPDATE_ID" | jq

Get updates with timeout (long polling)

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?timeout=30" | jq

Webhooks

Set webhook

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

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo" | jq

Delete webhook

curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook" | jq

Chat Management

Get chat info

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChat?chat_id=CHAT_ID" | jq

Get chat member count

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChatMemberCount?chat_id=CHAT_ID" | jq

Get chat administrators

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getChatAdministrators?chat_id=CHAT_ID" | jq

Ban user from chat

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

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

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

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

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

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

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

<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)

#!/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

# 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

# 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

Usage

Bot Information

Get bot info

Get bot commands

Set bot commands

Sending Messages

Send text message

Send message with inline keyboard

Send message with reply keyboard

Send photo

Send photo by URL

Send document

Send location

Getting Updates

Get updates (polling)

Get updates with offset (mark as read)

Get updates with timeout (long polling)

Webhooks

Set webhook

Get webhook info

Delete webhook

Chat Management

Get chat info

Get chat member count

Get chat administrators

Ban user from chat

Unban user

Message Management

Edit message text

Delete message

Pin message

Forward message

Callback Queries

Answer callback query

Notes

HTML Formatting

Examples

Simple echo bot (bash script)

Get your chat ID

Send to channel

Useful Resources

telegram-bot

Telegram Bot Builder Skill

Setup

API Base URL