Telegram Bot API

Getting Started

Obtain Bot Token

1. Message @BotFather on Telegram
2. Send /newbot command
3. Follow instructions to create your bot
4. Copy the token provided (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Getting Chat ID

Individual Chat ID

Send a message to your bot, then get updates:

curl https://api.telegram.org/bot[bot_token]/getUpdates

Look for the "chat":{"id":...} field in the response.

Group Chat ID

Step 1: Add your bot to the group

Step 2: Send a message mentioning the bot

@YourBotName /start

Note: This gives the bot access to group messages.

Step 3: Get updates

curl https://api.telegram.org/bot[bot_token]/getUpdates

Step 4: Find the chat object in the response

{
  "update_id": 8393,
  "message": {
    "message_id": 3,
    "from": {
      "id": 7474,
      "first_name": "User Name"
    },
    "chat": {
      "id": -1001234567890,
      "title": "Group Name",
      "type": "group"
    },
    "date": 1637766400,
    "new_chat_participant": {
      "id": 123456789,
      "first_name": "Bot Name",
      "username": "YourBotName"
    }
  }
}

💡 Tip: Group chat IDs are always negative. Private chat IDs are positive.

⚠️ Troubleshooting: If you get {"ok":true,"result":[]}, remove and re-add the bot to the group.

Sending Messages

Send Text Message

Parameters:

• chat_id (Required): Unique identifier for the target chat or username of the target channel.
• text (Required): Text of the message to be sent.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -d chat_id=[chat_id] \
  -d text="[message]"

Send Message with Markdown

Parameters:

• parse_mode (Optional): Mode for parsing entities in the message text. Use Markdown or MarkdownV2.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -d chat_id=[chat_id] \
  -d text="*bold* _italic_ \`code\`" \
  -d parse_mode=Markdown

Send Message with HTML

Parameters:

• parse_mode (Optional): Mode for parsing entities in the message text. Use HTML.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -d chat_id=[chat_id] \
  -d text="<b>bold</b> <i>italic</i> <code>code</code>" \
  -d parse_mode=HTML

Sending Media

Send Photo

Parameters:

• photo (Required): Photo to send. Upload a new photo using multipart/form-data.
• caption (Optional): Photo caption (0-1024 characters).

curl -X POST https://api.telegram.org/bot[bot_token]/sendPhoto \
  -F chat_id=[chat_id] \
  -F photo=@/path/to/image.jpg \
  -F caption="Photo caption"

Send Photo by URL

Parameters:

• photo (Required): Pass an HTTP URL as a String for Telegram to get a photo from the Internet.

curl -X POST https://api.telegram.org/bot[bot_token]/sendPhoto \
  -d chat_id=[chat_id] \
  -d photo="https://example.com/image.jpg"

Send Document

Parameters:

• document (Required): File to send. Upload a new file using multipart/form-data.

curl -X POST https://api.telegram.org/bot[bot_token]/sendDocument \
  -F chat_id=[chat_id] \
  -F document=@/path/to/file.pdf

Bot Commands

Get Bot Information

curl https://api.telegram.org/bot[bot_token]/getMe

Get Updates (Long Polling)

curl https://api.telegram.org/bot[bot_token]/getUpdates

Get Updates with Offset

curl https://api.telegram.org/bot[bot_token]/getUpdates?offset=12345

💡 Tip: Use offset to acknowledge processed updates.

Set Webhook (Push Updates)

curl -X POST https://api.telegram.org/bot[bot_token]/setWebhook \
  -d url="https://your-domain.com/webhook"

Delete Webhook

curl -X POST https://api.telegram.org/bot[bot_token]/deleteWebhook

Advanced Features

Send Message with Inline Keyboard

Parameters:

• reply_markup (Optional): Additional interface options. A JSON-serialized object for an inline keyboard.

curl -X POST https://api.telegram.org/bot[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"}
      ]]
    }
  }'

Send Message with Reply Keyboard

Parameters:

• reply_markup (Optional): Additional interface options. A JSON-serialized object for a custom reply keyboard.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "[chat_id]",
    "text": "Select an option:",
    "reply_markup": {
      "keyboard": [["Button 1", "Button 2"], ["Button 3"]],
      "resize_keyboard": true,
      "one_time_keyboard": true
    }
  }'

Edit Message Text

Parameters:

• message_id (Required): Identifier of the message to edit.
• text (Required): New text of the message.

curl -X POST https://api.telegram.org/bot[bot_token]/editMessageText \
  -d chat_id=[chat_id] \
  -d message_id=123 \
  -d text="Updated message"

Delete Message

Parameters:

• message_id (Required): Identifier of the message to delete.

curl -X POST https://api.telegram.org/bot[bot_token]/deleteMessage \
  -d chat_id=[chat_id] \
  -d message_id=123

Group Management

Get Chat Information

Parameters:

• chat_id (Required): Unique identifier for the target chat.

curl https://api.telegram.org/bot[bot_token]/getChat?chat_id=[chat_id]

Get Chat Administrators

Parameters:

• chat_id (Required): Unique identifier for the target chat.

curl https://api.telegram.org/bot[bot_token]/getChatAdministrators?chat_id=[chat_id]

Get Chat Member Count

Parameters:

• chat_id (Required): Unique identifier for the target chat.

curl https://api.telegram.org/bot[bot_token]/getChatMemberCount?chat_id=[chat_id]

Ban User

Parameters:

• user_id (Required): Unique identifier of the target user.

curl -X POST https://api.telegram.org/bot[bot_token]/banChatMember \
  -d chat_id=[chat_id] \
  -d user_id=123456789

Unban User

Parameters:

• user_id (Required): Unique identifier of the target user.

curl -X POST https://api.telegram.org/bot[bot_token]/unbanChatMember \
  -d chat_id=[chat_id] \
  -d user_id=123456789

Using JSON Payload

Send Complex Message with JSON

Parameters:

• disable_web_page_preview (Optional): Disables link previews for links in this message.
• disable_notification (Optional): Sends the message silently.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "[chat_id]",
    "text": "Hello, *World*!",
    "parse_mode": "Markdown",
    "disable_web_page_preview": true,
    "disable_notification": true
  }'

Useful Tips

Silent Messages

Send messages without notification sound:

Parameters:

• disable_notification (Optional): Sends the message silently. Users will receive a notification with no sound.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -d chat_id=[chat_id] \
  -d text="Silent message" \
  -d disable_notification=true

Disable Link Preview

Parameters:

• disable_web_page_preview (Optional): Disables link previews for links in this message.

curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
  -d chat_id=[chat_id] \
  -d text="https://example.com" \
  -d disable_web_page_preview=true

Send to Multiple Chats

for chat in [chat_id1] [chat_id2] [chat_id3]; do
  curl -X POST https://api.telegram.org/bot[bot_token]/sendMessage \
    -d chat_id=$chat \
    -d text="Hello from Bot!"
done

Error Handling

Check API Response

curl -s https://api.telegram.org/bot[bot_token]/getMe | jq .

Common Error Codes

Resources

• Official Bot API Documentation
• BotFather Commands
• Telegram Bot Examples