telegram

name	telegram
description	Interact with Telegram Bot API: send messages/photos/files/videos/audio/stickers/polls to any chat/group/channel, manage groups (pin/unpin/ban/kick/promote/restrict/set title/description/photo), forward/copy/delete/edit messages, react to messages, create invite links, manage forum topics, inline keyboards, and more. Use for ANY Telegram operation.
allowed-tools	["Bash"]

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

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

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

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