Telegram Bot API Skill

You have full access to the Telegram Bot API. Use CLI commands for common operations, and direct API calls for everything else.

Getting the Bot Token

BOT_TOKEN=$(curl -s http://localhost:23001/api/settings | jq -r '.telegram.botToken')

API Call Pattern

# JSON body (most methods)
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/<METHOD>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Multipart form (file uploads)
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/<METHOD>" \
  -F "chat_id=<CHAT_ID>" \
  -F "photo=@/path/to/file.jpg" \
  -F "caption=optional caption"

Full API docs: https://core.telegram.org/bots/api

CLI Quick Commands

# Current chat (ALMA_CHAT_ID auto-set)
alma send photo /path/to/img.jpg "caption"
alma send file /path/to/doc.pdf "caption"
alma send audio /path/to/song.mp3
alma send video /path/to/vid.mp4

# Group operations
alma group list
alma group send <chatId> "text"
alma group send-photo <chatId> /path "caption"
alma group send-document <chatId> /path "caption"
alma group send-video <chatId> /path "caption"
alma group history <chatId> [limit]
alma group search <chatId> "query"
alma group context <chatId>
alma group pin <chatId> <msgId>
alma group unpin <chatId> [msgId]
alma group leave <chatId>
alma group patrol

# Direct message & message mgmt
alma dm <userId> "message"
alma msg delete <chatId> <msgId>
alma msg react <chatId> <msgId> <emoji>   # Add reaction to a message (e.g. ❤️ 😂 👍)
alma msg sticker <chatId> <sticker_file_id>  # Send a sticker (use file_id from received stickers)
alma msg sticker-search [set_name]          # List sticker sets (no args) or index a specific set
alma msg sticker-find <emoji>               # Find stickers by emoji across all indexed sets

All Telegram Bot API Methods

Sending Messages

Forwarding & Copying

Editing Messages

Reactions

Chat Management

Member Management

Invite Links

Forum Topics

Bot Profile

User Info

Files

Inline Keyboards & Callbacks

// reply_markup for inline buttons
{
  "inline_keyboard": [
    [{"text": "Button 1", "callback_data": "btn1"}, {"text": "URL", "url": "https://example.com"}],
    [{"text": "Row 2", "callback_data": "btn2"}]
  ]
}

Stickers

Payments

Games

Common Examples

Post to a channel

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "@channel_username", "text": "Hello!"}'

Send photo with inline keyboard

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendPhoto" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'$ALMA_CHAT_ID'",
    "photo": "https://example.com/image.jpg",
    "caption": "Check this out!",
    "reply_markup": {"inline_keyboard": [[{"text":"👍 Like","callback_data":"like"},{"text":"👎","callback_data":"dislike"}]]}
  }'

Forward message between chats

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/forwardMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "<TARGET>", "from_chat_id": "<SOURCE>", "message_id": 123}'

Create a poll

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "'$ALMA_CHAT_ID'", "question": "Best language?", "options": [{"text":"Rust"},{"text":"TypeScript"},{"text":"Python"}], "is_anonymous": false}'

Reply to a specific message

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "'$ALMA_CHAT_ID'", "text": "Replying!", "reply_parameters": {"message_id": 5678}}'

Promote user to admin

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/promoteChatMember" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "<GROUP>", "user_id": 12345, "can_pin_messages": true, "can_invite_users": true}'

Upload and send a local file

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendDocument" \
  -F "chat_id=$ALMA_CHAT_ID" \
  -F "document=@/path/to/file.pdf" \
  -F "caption=Here's the document"

Send album (media group)

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendMediaGroup" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "'$ALMA_CHAT_ID'", "media": [
    {"type":"photo","media":"https://example.com/1.jpg","caption":"First"},
    {"type":"photo","media":"https://example.com/2.jpg"}
  ]}'

Create invite link

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/createChatInviteLink" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "<GROUP>", "name": "My Link", "member_limit": 100}'

Tips

• Channel posts: Use @channel_username or numeric chat_id (starts with -100)
• Bot must be admin to: post to channels, pin, delete others' messages, ban, manage topics
• ALMA_CHAT_ID is auto-set in Bash tool env — use it for current chat
• File uploads: Use -F multipart form, not -d JSON
• parse_mode: Use "HTML" for <b>bold</b> <i>italic</i> <code>code</code> <a href="url">link</a>
• Group IDs are negative; user IDs are positive
• Message IDs are visible as [msg:xxx] in chat
• For methods not listed here, check https://core.telegram.org/bots/api