Telegram

Messaging bots. Send and edit text, photo, and document messages, pin them, run polls, and administer a group and its members.

Measured routing accuracy

40 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 28 cases written by hand and 12 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

api_key

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

28 action tools. The catalog-wide slug is telegram.<tool>, which is what search_tools returns and call_tool takes.

telegram.get_me

Get the identity of the connected Telegram bot itself: its id, username, and display name. Use when the user asks which bot this integration is running as, or wants to confirm the bot token is working at all.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getMe.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "which bot am I actually running as", "check that the bot token still works", "what's this integration's own identity", "show me this bot's own profile".

telegram.send_message

Send a text message to a Telegram chat, group, or channel right now. Use when the user wants to send, post, message, or notify people on Telegram. Set reply_to_message_id to quote a specific earlier message, and parse_mode to send Markdown or HTML formatting.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /sendMessage.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "broadcast something to the whole group", "shout something out to the whole channel", "let the group know what's going on", "quote an earlier message when responding", "fire off a quick line in the chat", "ping everyone in the channel with an update".

telegram.send_photo

Send a photo to a Telegram chat by its URL, with an optional caption. Use when the user wants to send, share, or post a picture or image on Telegram. For any other file type, use send_document instead.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /sendPhoto.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "share a picture with the group", "post an image in the channel", "drop a screenshot into the chat", "send someone a picture by link".

telegram.send_document

Send a file to a Telegram chat by its URL, with an optional caption. Use when the user wants to send, share, or attach a document, PDF, or other file on Telegram. For an image meant to display inline, use send_photo instead.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /sendDocument.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "attach a PDF to the chat", "share a file with the group", "send over that spreadsheet as an attachment", "drop a report into the channel".

telegram.edit_message_text

Change the text of a message the bot already sent. Use when the user wants to fix, correct, or update a Telegram message that was already posted. Only messages the bot itself sent can be edited, and only while they are recent enough for Telegram to allow it.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /editMessageText.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix a typo in something the bot posted", "reword what got sent earlier", "clean up the wording in the last post", "change what was typed by mistake".

telegram.delete_message

Delete one message from a Telegram chat. Use when the user wants to remove, retract, or take down a message. Permanent: the message cannot be restored, and the bot must be an admin to delete a message it did not send itself.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /deleteMessage.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take back something that got posted", "erase a post someone regrets sending", "pull down what was just written in the chat", "undo a message sent by mistake", "wipe one bad post out of the group".

telegram.forward_message

Forward an existing message, as-is, from one chat into another. Use when the user wants to forward, relay, or repost a message somewhere else on Telegram without retyping it.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /forwardMessage.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "relay this post into another group", "repost something without retyping it", "send this along to a different channel", "share the exact same message elsewhere".

telegram.get_updates

Poll for new incoming messages, edits, and other events the bot has not yet seen. Use when the user wants to check, fetch, or catch up on new Telegram activity. Pass offset one past the highest update_id already handled to avoid seeing the same update twice.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getUpdates.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what did I miss since last time", "check for any new incoming messages", "catch up on activity the bot hasn't seen yet", "pull the latest events waiting for the bot".

telegram.send_chat_action

Show a transient status, like "typing" or "uploading photo", in a chat. Use when the user wants the bot to look like it's actively working before a slower response lands. The indicator clears itself after about five seconds or as soon as a message is sent.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /sendChatAction.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "make it look like the bot is typing", "show a working indicator before the answer lands", "flash the uploading status while a file is prepared".

telegram.pin_chat_message

Pin a message to the top of a chat. Use when the user wants to pin, highlight, or keep a Telegram message easy to find later. Reversible with unpin_chat_message.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /pinChatMessage.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "stick that message to the top of the group", "highlight a post so it's easy to find later", "keep this one visible for everyone", "flag a message as important in the chat".

telegram.unpin_chat_message

Remove one message from a chat's pinned list. Use when the user wants to unpin a specific message. Omit message_id to unpin whichever message is currently pinned most recently. For clearing every pin at once, use unpin_all_chat_messages.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /unpinChatMessage.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take that pinned post off the top", "stop highlighting a message that's no longer relevant", "clear a pin from the chat header", "remove something from the pinned list".

telegram.unpin_all_chat_messages

Clear every pinned message in a chat at once. Use when the user wants to unpin everything, clear all pins, or start a chat's pinned list over. Only affects pinned status; the messages themselves stay in the chat. For a single pin, use unpin_chat_message.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /unpinAllChatMessages.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "clear every pin in this group at once", "start the pinned list over from scratch", "wipe out all the highlighted posts together".

telegram.send_poll

Post a poll or quiz to a chat with a question and answer options. Use when the user wants to run, create, or send a poll or vote on Telegram. Set type to "quiz" for a single correct answer instead of an open vote.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /sendPoll.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "run a quick vote in the group", "ask everyone to pick an option", "set up a quiz with a right answer", "see what people prefer with a poll".

telegram.stop_poll

Close a poll early so no more votes are accepted, and get its final results. Use when the user wants to end, close, or finalize a Telegram poll before it would otherwise stay open.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /stopPoll.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "end the vote early and show results", "close out that quiz now", "lock in the final poll numbers".

telegram.get_chat

Get a Telegram chat's details: its type, title, username, and description. Use when the user asks about a specific group, channel, or conversation as a whole, or wants to resolve a chat's invite link.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getChat.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "tell me about this particular group", "what's the description on this channel", "give me the basics on one chat", "look up this group's invite link".

telegram.get_chat_administrators

List every admin and the owner of a chat, with their status and custom title. Use when the user asks who moderates or owns a Telegram group or channel. For one member's own status, use get_chat_member.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getChatAdministrators.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who moderates this group", "show me everyone with admin powers here", "who runs this channel", "list the mods for this chat".

telegram.get_chat_member_count

Get the total number of members in a chat. Use when the user asks how big a Telegram group or channel is, or how many people are in it.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getChatMemberCount.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "how many people are in this group", "how big is this channel", "what's the headcount for this chat".

telegram.get_chat_member

Get one chat member's status by user id: whether they're the owner, an admin, a regular member, restricted, or banned. Use when the user asks about a specific person's standing in a Telegram chat. For every admin at once, use get_chat_administrators.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /getChatMember.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's this person's standing in the group", "is this user still a member or were they banned", "look someone up by their id in this chat", "check if someone's an admin here".

telegram.set_chat_title

Rename a Telegram group or channel. Use when the user wants to rename, retitle, or change the name of a chat. The bot needs admin rights in the chat.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /setChatTitle.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "rename this group", "change the name shown on this channel", "give this chat a new title".

telegram.set_chat_description

Change a Telegram group or channel's description text. Use when the user wants to update, edit, or set the description shown on a chat's info page. The bot needs admin rights in the chat.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /setChatDescription.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "update the about text for this group", "change what shows in the channel's about text", "set what shows on the chat's info page".

telegram.ban_chat_member

Ban a member from a group or channel, removing them and blocking them from rejoining until unban_chat_member is called. Use when the user wants to ban, permanently remove, or block someone on Telegram. Optionally deletes all of their messages in the chat via revoke_messages.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls POST /banChatMember.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "permanently remove a troublemaker from the group", "block someone from ever rejoining this channel", "kick someone out for good and wipe their messages".

telegram.unban_chat_member

Lift a ban so the person can rejoin a group or channel. Use when the user wants to unban, reinstate, or forgive someone who was previously banned on Telegram. They still need a fresh invite to actually come back if the chat is private.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /unbanChatMember.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "lift a ban on someone", "let a banned person back into the group", "forgive someone who was previously blocked", "reverse a ban so they can rejoin".

telegram.restrict_chat_member

Limit what a member can do in a group without removing them: mute them, or stop them sending media, polls, or invite links. Use when the user wants to restrict, mute, or silence someone on Telegram. Restore full permissions by calling again with every flag true.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /restrictChatMember.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "mute someone in the group", "stop a person from sending media for a while", "silence a member without kicking them", "limit what someone's allowed to post here".

telegram.promote_chat_member

Grant a member admin rights in a group or channel, such as deleting messages, inviting users, or pinning. Use when the user wants to promote, make an admin, or grant moderator powers to someone on Telegram. Call again with every right false to demote them.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /promoteChatMember.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "make someone an admin in this group", "grant moderator powers to a member", "give someone the ability to delete posts and invite people", "demote an admin back to a regular member".

telegram.set_chat_administrator_custom_title

Set the custom title shown next to an admin's name in a group, like "Support Lead" instead of the default "Admin". Use when the user wants to relabel, rename, or set a custom admin title for someone on Telegram. The member must already be an admin.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /setChatAdministratorCustomTitle.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give an admin a custom label instead of the default", "relabel a moderator's title in the group", "set what shows next to an admin's name here".

telegram.exit_chat

Remove the bot itself from a group or channel. Use when the user wants the bot taken out of, exited from, or removed from a Telegram chat entirely. The bot can be re-added later with a fresh invite; the chat and its history are untouched.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /leaveChat.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "have the bot exit this group", "remove the bot from this channel", "take the bot out of this chat for now".

telegram.create_chat_invite_link

Create a new invite link for a group or channel. Use when the user wants to invite, share access, or generate a link for someone to join a Telegram chat. expire_date and member_limit cap when it stops working and how many people can use it.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /createChatInviteLink.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "make me a join link for this group", "generate a way for someone to get into the channel", "set up an invite that expires soon", "give me a link with a limited number of uses".

telegram.revoke_chat_invite_link

Revoke an existing invite link so it can no longer be used to join. Use when the user wants to revoke, cancel, or kill a Telegram invite link. A new one can be created immediately with create_chat_invite_link.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /revokeChatInviteLink.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "kill an invite link", "cancel a join link before it's abused", "shut down a link someone shared by mistake".