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

bash

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

API Call Pattern

bash

# 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

bash

# 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

Method	Description
`sendMessage`	Send text message. Params: `chat_id` , `text` , `parse_mode` (HTML/Markdown), `reply_parameters` , `reply_markup` , `message_thread_id` , `link_preview_options`
`sendPhoto`	Send photo. `chat_id` , `photo` (file_id/URL/upload), `caption` , `has_spoiler`
`sendDocument`	Send file. `chat_id` , `document` , `caption` , `thumbnail`
`sendVideo`	Send video. `chat_id` , `video` , `caption` , `duration` , `width` , `height` , `has_spoiler`
`sendAnimation`	Send GIF. `chat_id` , `animation` , `caption` , `has_spoiler`
`sendAudio`	Send audio. `chat_id` , `audio` , `caption` , `duration` , `performer` , `title`
`sendVoice`	Send voice message. `chat_id` , `voice` , `caption` , `duration`
`sendVideoNote`	Send round video. `chat_id` , `video_note` , `duration` , `length`
`sendSticker`	Send sticker. `chat_id` , `sticker` (file_id/URL/upload)
`sendLocation`	Send location. `chat_id` , `latitude` , `longitude` , `live_period`
`sendVenue`	Send venue. `chat_id` , `latitude` , `longitude` , `title` , `address`
`sendContact`	Send contact. `chat_id` , `phone_number` , `first_name` , `last_name`
`sendPoll`	Send poll. `chat_id` , `question` , `options` ([{text:...}]), `is_anonymous` , `type` (quiz/regular), `allows_multiple_answers`
`sendDice`	Send dice/slot. `chat_id` , `emoji` (🎲🎯🏀⚽🎳🎰)
`sendMediaGroup`	Send album (2-10 items). `chat_id` , `media` ([{type,media,caption}])
`sendChatAction`	Show typing/uploading status. `chat_id` , `action` (typing/upload_photo/upload_video/upload_document/record_voice/record_video/etc)
`sendMessageDraft`	Stream partial message. `chat_id` , `text` , `business_connection_id`

Forwarding & Copying

Method	Description
`forwardMessage`	Forward message. `chat_id` (target), `from_chat_id` , `message_id`
`forwardMessages`	Forward multiple. `chat_id` , `from_chat_id` , `message_ids` ([array])
`copyMessage`	Copy without "Forwarded" header. `chat_id` , `from_chat_id` , `message_id` , `caption`
`copyMessages`	Copy multiple. `chat_id` , `from_chat_id` , `message_ids`

Editing Messages

Method	Description
`editMessageText`	Edit text. `chat_id` , `message_id` , `text` , `parse_mode` , `reply_markup`
`editMessageCaption`	Edit caption. `chat_id` , `message_id` , `caption`
`editMessageMedia`	Edit media. `chat_id` , `message_id` , `media`
`editMessageReplyMarkup`	Edit inline keyboard. `chat_id` , `message_id` , `reply_markup`
`editMessageLiveLocation`	Update live location. `chat_id` , `message_id` , `latitude` , `longitude`
`stopMessageLiveLocation`	Stop live location. `chat_id` , `message_id`
`deleteMessage`	Delete message. `chat_id` , `message_id`
`deleteMessages`	Delete multiple. `chat_id` , `message_ids` ([array])

Reactions

Method	Description
`setMessageReaction`	React to message. `chat_id` , `message_id` , `reaction` ([{"type":"emoji","emoji":"👍"}]), `is_big`

Chat Management

Method	Description
`getChat`	Get chat info. `chat_id`
`getChatMemberCount`	Member count. `chat_id`
`getChatMember`	Get one member's info. `chat_id` , `user_id`
`getChatAdministrators`	List admins. `chat_id`
`setChatTitle`	Set title. `chat_id` , `title`
`setChatDescription`	Set description. `chat_id` , `description`
`setChatPhoto`	Set photo. `chat_id` , `photo` (upload)
`deleteChatPhoto`	Delete photo. `chat_id`
`setChatPermissions`	Set default permissions. `chat_id` , `permissions` ({can_send_messages, can_send_photos, ...})
`setChatStickerSet`	Set sticker set. `chat_id` , `sticker_set_name`
`deleteChatStickerSet`	Remove sticker set. `chat_id`
`leaveChat`	Leave chat. `chat_id`
`pinChatMessage`	Pin message. `chat_id` , `message_id` , `disable_notification`
`unpinChatMessage`	Unpin message. `chat_id` , `message_id`
`unpinAllChatMessages`	Unpin all. `chat_id`

Member Management

Method	Description
`banChatMember`	Ban user. `chat_id` , `user_id` , `until_date` , `revoke_messages`
`unbanChatMember`	Unban user. `chat_id` , `user_id` , `only_if_banned`
`restrictChatMember`	Restrict user. `chat_id` , `user_id` , `permissions` , `until_date`
`promoteChatMember`	Promote to admin. `chat_id` , `user_id` , `can_change_info` , `can_post_messages` , `can_edit_messages` , `can_delete_messages` , `can_invite_users` , `can_restrict_members` , `can_pin_messages` , `can_promote_members` , `can_manage_video_chats` , `can_manage_chat`
`setChatAdministratorCustomTitle`	Set admin title. `chat_id` , `user_id` , `custom_title`
`approveChatJoinRequest`	Approve join request. `chat_id` , `user_id`
`declineChatJoinRequest`	Decline join request. `chat_id` , `user_id`

Invite Links

Method	Description
`exportChatInviteLink`	Create new primary link. `chat_id`
`createChatInviteLink`	Create invite link. `chat_id` , `name` , `expire_date` , `member_limit` , `creates_join_request`
`editChatInviteLink`	Edit invite link. `chat_id` , `invite_link` , ...
`revokeChatInviteLink`	Revoke link. `chat_id` , `invite_link`
`createChatSubscriptionInviteLink`	Paid subscription link. `chat_id` , `subscription_period` , `subscription_price`

Forum Topics

Method	Description
`createForumTopic`	Create topic. `chat_id` , `name` , `icon_color` , `icon_custom_emoji_id`
`editForumTopic`	Edit topic. `chat_id` , `message_thread_id` , `name` , `icon_custom_emoji_id`
`closeForumTopic`	Close topic. `chat_id` , `message_thread_id`
`reopenForumTopic`	Reopen topic. `chat_id` , `message_thread_id`
`deleteForumTopic`	Delete topic. `chat_id` , `message_thread_id`
`unpinAllForumTopicMessages`	Unpin all in topic. `chat_id` , `message_thread_id`
`getForumTopicIconStickers`	Get available topic icons
`editGeneralForumTopic`	Edit General topic. `chat_id` , `name`
`closeGeneralForumTopic`	Close General. `chat_id`
`reopenGeneralForumTopic`	Reopen General. `chat_id`
`hideGeneralForumTopic`	Hide General. `chat_id`
`unhideGeneralForumTopic`	Unhide General. `chat_id`

Bot Profile

Method	Description
`getMe`	Get bot info
`setMyName`	Set bot name. `name` , `language_code`
`getMyName`	Get bot name
`setMyDescription`	Set bot description. `description` , `language_code`
`getMyDescription`	Get bot description
`setMyShortDescription`	Set short description. `short_description`
`getMyShortDescription`	Get short description
`setMyProfilePhoto`	Set bot profile photo. `photo`
`removeMyProfilePhoto`	Remove bot profile photo
`setMyCommands`	Set command list. `commands` ([{command,description}]), `scope` , `language_code`
`getMyCommands`	Get commands
`deleteMyCommands`	Delete commands
`setChatMenuButton`	Set menu button. `chat_id` , `menu_button`
`getChatMenuButton`	Get menu button
`setMyDefaultAdministratorRights`	Set default admin rights. `rights` , `for_channels`
`getMyDefaultAdministratorRights`	Get default admin rights

User Info

Method	Description
`getUserProfilePhotos`	Get profile photos. `user_id` , `offset` , `limit`
`getUserProfileAudios`	Get profile audios. `user_id`

Files

Method	Description
`getFile`	Get file download info. `file_id` . Download: `https://api.telegram.org/file/bot<TOKEN>/<file_path>`

Inline Keyboards & Callbacks

json

// 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"}]
  ]
}

Method	Description
`answerCallbackQuery`	Answer callback from inline button. `callback_query_id` , `text` , `show_alert`

Stickers

Method	Description
`sendSticker`	Send sticker. `chat_id` , `sticker`
`getStickerSet`	Get sticker set. `name`
`getCustomEmojiStickers`	Get custom emoji. `custom_emoji_ids`
`createNewStickerSet`	Create sticker set. `user_id` , `name` , `title` , `stickers`
`addStickerToSet`	Add sticker. `user_id` , `name` , `sticker`
`setStickerPositionInSet`	Reorder. `sticker` , `position`
`deleteStickerFromSet`	Delete sticker. `sticker`
`setStickerSetTitle`	Set title. `name` , `title`
`setStickerSetThumbnail`	Set thumbnail. `name` , `user_id` , `thumbnail`

Payments

Method	Description
`sendInvoice`	Send invoice. `chat_id` , `title` , `description` , `payload` , `currency` , `prices`
`createInvoiceLink`	Create payment link
`answerShippingQuery`	Answer shipping. `shipping_query_id` , `ok` , `shipping_options`
`answerPreCheckoutQuery`	Answer checkout. `pre_checkout_query_id` , `ok`
`refundStarPayment`	Refund stars. `user_id` , `telegram_payment_charge_id`

Games

Method	Description
`sendGame`	Send game. `chat_id` , `game_short_name`
`setGameScore`	Set score. `user_id` , `score` , `chat_id` , `message_id`
`getGameHighScores`	Get scores. `user_id` , `chat_id` , `message_id`

Common Examples

Post to a channel

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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)

bash

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

bash

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

telegram

NPX Install

Tags

SKILL.md Content

Telegram Bot API Skill

Getting the Bot Token

API Call Pattern

CLI Quick Commands

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

Stickers

Payments

Games

Common Examples

Post to a channel

Send photo with inline keyboard

Forward message between chats

Create a poll

Reply to a specific message

Promote user to admin

Upload and send a local file

Send album (media group)

Create invite link

Tips