ESC
Start typing to search...

Telegram Tools

76 built-in tools covering every aspect of Telegram: sending and scheduling messages, managing media, channels, groups, polls, stickers, folders, profiles, Telegram Stars, gifts, contacts, stories, agent memory, and scheduled tasks.

Each tool has a scope that controls when it is available:

  • always — available in all contexts (DMs and groups).
  • dm-only — only available in direct message conversations.
  • group-only — only available inside group or channel chats.
  • admin-only — only available to users listed in telegram.admin_ids.

Scopes can be overridden per-tool at runtime via the tool_config table in the memory database.

Messaging (13)

ToolScopeDescriptionParameters
telegram_send_message always Send a plain-text message to any chat, user, or channel. chatId string (req), text string max 4096 (req), replyToId number (opt)
telegram_edit_message always Edit the text of a previously sent message. chatId string (req), messageId number (req), text string (req)
telegram_delete_message always Delete one or more messages. Optionally revoke for all participants. chatId string (req), messageIds number[] (req), revoke boolean (opt)
telegram_forward_message always Forward one or more messages from one chat to another. fromChatId string (req), toChatId string (req), messageIds number[] (req), silent boolean (opt), background boolean (opt)
telegram_quote_reply always Reply to a message with a specific quote selection highlighted. chatId string (req), messageId number (req), quoteText string (req), text string (req), quoteOffset number (opt)
telegram_get_replies always Fetch replies to a specific message in a group or channel thread. chatId string (req), messageId number (req), limit number default 50 (opt)
telegram_schedule_message always Schedule a text message to be sent at a future date and time. chatId string (req), text string (req), scheduleDate string ISO 8601 (req)
telegram_get_scheduled_messages always List all scheduled (pending) messages in a chat, including text, scheduled time, and IDs. chatId string (req)
telegram_delete_scheduled_message always Delete one or more scheduled messages before they are sent. chatId string (req), messageIds number[] 1–30 (req)
telegram_send_scheduled_now always Send one or more scheduled messages immediately instead of waiting. chatId string (req), messageIds number[] 1–30 (req)
telegram_search_messages always Full-text search through messages in a specific chat. chatId string (req), query string (req), limit number default 50 max 100 (opt)
telegram_pin_message always Pin a message in a chat. Optionally pin silently or for both sides in DMs. chat_id string (req), message_id number (req), silent boolean (opt), both_sides boolean (opt)
telegram_unpin_message always Unpin a specific message or all pinned messages in a chat. chat_id string (req), message_id number (opt), unpin_all boolean (opt)

Media (7)

ToolScopeDescriptionParameters
telegram_send_photo always Send a photo from a local file path to a chat. chatId string (req), photoPath string (req), caption string (opt), replyToId number (opt)
telegram_send_voice always Send a voice message. Can use a pre-existing audio file or synthesise speech from text via a TTS provider. chatId string (req), voicePath string (opt), text string (opt), voice string (opt), ttsProvider string piper/edge/openai/elevenlabs (opt), rate string (opt), duration number (opt), waveform number[] (opt), caption string (opt), replyToId number (opt)
telegram_send_sticker always Send a sticker by set name + index, or from a local file. chatId string (req), stickerSetShortName string (opt), stickerIndex number (opt), stickerPath string (opt), replyToId number (opt)
telegram_send_gif always Send a GIF from an inline query result or a local file path. chatId string (req), queryId string (opt), resultId string (opt), gifPath string (opt), caption string (opt), replyToId number (opt)
telegram_download_media always Download media attached to a message and save it to the agent workspace. chatId string (req), messageId number (req), filename string (opt)
vision_analyze always Analyse an image using the configured vision model. Can reference a Telegram message or a local file. chatId string (opt), messageId number (opt), filePath string (opt), prompt string (opt)
telegram_transcribe_audio always Transcribe a voice message or audio file attached to a Telegram message. chatId string (req), messageId number (req)

Chats & Channels (12)

ToolScopeDescriptionParameters
telegram_get_dialogs always List recent conversations (dialogs). Supports filtering for unread or archived chats. limit number (opt), archived boolean (opt), unreadOnly boolean (opt)
telegram_get_history always Fetch message history from a chat with optional pagination. chatId string (req), limit number max 100 (opt), offsetId number (opt)
telegram_get_chat_info always Get detailed metadata for a chat, channel, or user. chatId string (req)
telegram_mark_as_read always Mark messages in a chat as read, optionally up to a specific message ID. chatId string (req), messageId number (opt), clearMentions boolean (opt)
telegram_join_channel dm-only Join a public channel or group by username or invite link. channel string (req)
telegram_leave_channel dm-only Leave a channel or group. channel string (req)
telegram_create_channel dm-only Create a new Telegram channel or supergroup. title string max 128 (req), about string (opt), megagroup boolean (opt), username string (opt)
telegram_edit_channel_info dm-only Edit the title or description of a channel the agent administers. channelId string (req), title string (opt), about string (opt)
telegram_invite_to_channel dm-only Invite one or more users to a channel by user ID or username. channelId string (req), userIds string[] (opt), usernames string[] (opt)
telegram_get_admined_channels dm-only List all channels and groups where the agent has admin rights. forPersonal boolean (opt)
telegram_check_channel_username dm-only Check whether a username is available for a given channel. channelId string (req), username string (req)
telegram_set_channel_username dm-only Set or change the public username of a channel the agent administers. channelId string (req), username string (req)

Groups & Members (7)

ToolScopeDescriptionParameters
telegram_get_me always Return the agent's own Telegram account information (name, username, ID). none
telegram_get_participants always List members of a group or channel with optional filter (admins, banned, bots, all). chatId string (req), filter string all/admins/banned/bots (opt), limit number max 200 (opt)
telegram_kick_user group-only Remove a user from a group. The user can rejoin unless subsequently banned. chat_id string (req), user_id string (req)
telegram_ban_user group-only Ban a user from a group, optionally deleting their recent messages and setting a duration. chat_id string (req), user_id string (req), delete_messages boolean (opt), duration_hours number (opt)
telegram_unban_user group-only Lift a ban and allow a user to rejoin a group or channel. chat_id string (req), user_id string (req)
telegram_create_group dm-only Create a new group chat and invite initial members. title string (req), users string[] min 1 (req)
telegram_set_chat_photo group-only Set or delete the profile photo of a group or channel. chat_id string (req), photo_path string (opt), delete_photo boolean (opt)

Interactive (5)

ToolScopeDescriptionParameters
telegram_create_poll always Send a poll with 2–10 options. Supports anonymous, multiple-choice, and time-limited polls. chatId string (req), question string (req), options string[] 2–10 (req), anonymous boolean (opt), multipleChoice boolean (opt), publicVoters boolean (opt), closePeriod number (opt), closeDate number (opt)
telegram_create_quiz always Send a quiz with a single correct answer, optional explanation, and time limit. chatId string (req), question string max 300 (req), options string[] 2–10 (req), correctOptionIndex number (req), explanation string (opt), closePeriod number (opt), closeDate number (opt)
telegram_reply_keyboard always Send a message with a custom reply keyboard (button grid). Supports one-time and resize options. chatId string (req), text string (req), buttons string[][] (req), oneTime boolean (opt), resize boolean (opt), selective boolean (opt), replyToId number (opt)
telegram_react always Add an emoji reaction to a message. chatId string (req), messageId number (req), emoji string (req)
telegram_send_dice always Send an animated dice or game emoji (dice, darts, basketball, football, slots, bowling). chat_id string (req), emoticon string dice/darts/basketball/football/slots/bowling (opt), reply_to number (opt)

Stickers & GIFs (4)

ToolScopeDescriptionParameters
telegram_search_stickers always Search Telegram's sticker catalogue by keyword and return matching sticker sets. query string (req), limit number max 50 (opt)
telegram_search_gifs always Search Telegram's inline GIF index by keyword. query string (req), limit number max 50 (opt)
telegram_get_my_stickers always List sticker sets the agent account has saved. limit number (opt)
telegram_add_sticker_set always Add a sticker set to the agent account by its short name. shortName string (req)

Folders (3)

ToolScopeDescriptionParameters
telegram_get_folders always List all chat folders configured on the agent account. none
telegram_create_folder always Create a new chat folder with optional emoji and automatic inclusion rules. title string max 12 (req), emoji string (opt), includeContacts boolean (opt), includeNonContacts boolean (opt), includeGroups boolean (opt), includeBroadcasts boolean (opt), includeBots boolean (opt)
telegram_add_chat_to_folder always Add an existing chat to a specific folder by folder ID. folderId number (req), chatId string (req)

Profile (4)

All profile tools are scoped to dm-only to prevent group members from triggering account changes.

ToolScopeDescriptionParameters
telegram_update_profile dm-only Update the agent account's first name, last name, and/or about text in one call. firstName string (opt), lastName string (opt), about string (opt)
telegram_set_bio dm-only Set the account bio (about text), maximum 70 characters. bio string max 70 (req)
telegram_set_username dm-only Set or clear the account's public username (0–32 characters, empty string to remove). username string 0–32 chars (req)
telegram_set_personal_channel dm-only Link a channel as the account's personal channel, or remove the current link. channelId string (opt)

Telegram Stars (2)

ToolScopeDescriptionParameters
telegram_get_stars_balance dm-only Get the current Telegram Stars balance of the agent account. Optionally include TON equivalent. ton boolean (opt)
telegram_get_stars_transactions dm-only Fetch recent Stars transaction history, filterable by direction. limit number max 100 (opt), inbound boolean (opt), outbound boolean (opt)

Gifts & Collectibles (13)

Gift tools leverage the GramJS Layer 222 API for Telegram's gift and collectible marketplace.

ToolScopeDescriptionParameters
telegram_get_available_gifts always Browse the gift catalogue. Supports filtering by type (limited/unlimited/resale), sorting, text search, and pagination. filter string all/limited/unlimited/resale (opt), includeSoldOut boolean (opt), limit number max 100 (opt), offset number (opt), sort string (opt), search string (opt)
telegram_send_gift dm-only Send a gift to a user. Requires a verified deal to be active. userId string (req), giftId string (req), message string (opt), anonymous boolean (opt)
telegram_get_my_gifts always List gifts owned by the agent or a specified user, with sort and filter options. userId string (opt), viewSender boolean (opt), limit number max 200 (opt), excludeUnsaved boolean (opt), excludeSaved boolean (opt), sortByValue boolean (opt)
telegram_transfer_collectible dm-only Transfer a unique collectible gift to another user. Requires a verified deal. msgId number (req), toUserId string (req)
telegram_set_collectible_price dm-only List a collectible for resale at a given price, or remove it from the marketplace. msgId number (req), price number (opt)
telegram_get_resale_gifts always Browse resale listings for a specific gift type, with optional price sorting. giftId string (req), limit number max 100 (opt), sortByPrice boolean (opt)
telegram_buy_resale_gift dm-only Purchase a unique collectible from the resale marketplace by its slug. slug string (req)
telegram_set_gift_status dm-only Toggle the saved/unsaved status of a collectible gift in the agent's collection. collectibleId string (opt), clear boolean (opt)
telegram_get_collectible_info always Look up ownership and metadata of a collectible by username or phone number. type string username/phone (req), value string (req)
telegram_get_unique_gift always Fetch full metadata for a unique gift by its slug. slug string (req)
telegram_get_unique_gift_value always Get the current market value (floor price) of a unique gift by slug. slug string (req)
telegram_send_gift_offer dm-only Propose a peer-to-peer gift trade offer to another user at a specified price and optional expiry. userId string (req), slug string (req), price number min 1 (req), duration number min 21600 (opt)
telegram_resolve_gift_offer dm-only Accept or decline a received gift offer by its message ID. offerMsgId number (req), decline boolean (opt)

Contacts & Users (5)

ToolScopeDescriptionParameters
telegram_block_user dm-only Block a user so they can no longer message the agent account. userId string (req)
telegram_get_blocked dm-only List users currently blocked by the agent account. limit number max 100 (opt)
telegram_get_common_chats always Find groups and channels shared between the agent and a given user. userId string (req), limit number max 100 (opt)
telegram_get_user_info always Retrieve public profile information for a user by ID or username. userId string (opt), username string (opt)
telegram_check_username always Check whether a Telegram username is taken or available. username string (req)

Stories (1)

ToolScopeDescriptionParameters
telegram_send_story dm-only Post a photo or video story with optional caption and privacy settings. mediaPath string (req), caption string max 200 (opt), privacy string everyone/contacts/close_friends (opt), duration number 1–60 (opt)

Memory (2)

Memory tools allow the agent to read from and write to its persistent and daily memory stores.

ToolScopeDescriptionParameters
memory_write dm-only Write a note or fact to persistent memory or today's daily log. Optionally target a specific section. content string (req), target string persistent/daily (req), section string (opt)
memory_read always Read from persistent memory, today's log, a past daily log by date, or list available log dates. target string persistent/daily/recent/list (req), date string YYYY-MM-DD (opt)

Scheduled Tasks (1)

ToolScopeDescriptionParameters
telegram_create_scheduled_task always Create a future task for the agent to execute autonomously at a given time. Supports priority, dependencies, and arbitrary JSON payload. description string (req), scheduleDate string ISO 8601 (opt), payload string JSON (opt), reason string (opt), priority number 0–10 (opt), dependsOn string[] (opt)