| name | telegram |
| description | Configure Telegram with /connect, then resolve Telegram user/group ids and search Telegram messages through the internal Telegram CLI. |
| allowed-tools | ["Bash"] |
| argument-hint | [Telegram login task] |
| arguments | target |
| user-invocable | false |
| disable-model-invocation | false |
Use /connect telegram-login <connection> when the user needs to authenticate
or repair a Telegram personal-account connection. That flow uses
AskUserQuestion for method choices and secrets.
Use the internal Telegram CLI when peer lookup, message listing, or message
search is needed. Run it from Bash as telegram ...; do not expose a
connector-specific slash command for Telegram. The CLI dispatches to the Telegram
subscriber and does not require a model turn.
Target: $target
Connection/account selection:
The default Telegram personal account connection is telegram-user. When the
user has multiple local Telegram accounts, use a distinct kebab-case connection
slug per account and pass it to every Telegram CLI command with --connection
or --account. Each slug maps to a separate supervised subscriber, topic, and
session file. --account-index is only the local import-time picker for
Telegram Desktop/native storage slots; it is not the stable account identity.
telegram --connection tg-alt search-peers "C & Jason" --kind group
After /connect login or import completes, the auth tool registers that
connection automatically with connector_slug="telegram-login". Use the same
connection slug in WorkflowCreate, ConnectorActionDraft, and ConnectorAct.
Peer lookup workflow:
When the user names a Telegram user, group, or channel and the next action
needs a send target or workflow filter, resolve the stable numeric id first.
Do not send to an ambiguous title directly.
telegram search-peers "C & Jason" --kind group
Use telegram list-peers --kind group --limit 50 to browse visible groups,
or omit --kind to include users, groups, and channels. The local command
returns the subscriber result directly. Use payload.peers[].id as the send
target or workflow chat id when JSON output is returned; it is a string on
purpose so large Telegram ids stay exact.
Message search workflow:
When the user asks to find text in Telegram, resolve the chat first and then
search messages by peer id. Prefer numeric peer ids over titles.
telegram search-peers "TonyKe" --kind user
telegram list-messages --peer 123456789 --limit 20
telegram list-messages --peer 123456789 --from "TonyKe" --scan-limit 200 --limit 20
telegram search-messages "karen" --peer 123456789 --context 0 --limit 10
Use telegram list-messages when the user asks to inspect recent chat history
without a specific search term. Use the returned --before-id cursor
to fetch older pages. Add --from <sender> when the user asks for messages
from one person in a group; the sender filter matches sender id, username,
@handle, or display name. The command scans a bounded recent window while
collecting sender matches; increase --scan-limit when a sparse sender needs a
deeper page. Use --context 0 for fast search; non-zero context returns
previous messages before each hit.
Use --succinct with the internal CLI for normal agent work. It returns plain
text context lines with relative offsets, for example -2 Sender: message,
instead of JSON. Only the message commands accept --succinct:
list-messages and search-messages support it; the peer commands
list-peers and search-peers do not (they always return their peer list).
Messages with downloadable media include a local file path; captions follow
the path on the same line. Text-only media such as polls are rendered as
text with answer indexes, for example
poll: Ship it? [open, 3 voters] | 0: Yes / 1: No. Replies are shown as a
prefix on the message line, for example [reply to #42: previous text].
Without --succinct, results are JSON; inspect payload.results[].context,
where the message with is_match: true is the search hit and earlier items are
previous-message context. JSON media is a string with the same contract: local
file path for downloaded media, or text for text-only media.
JSON poll is null or an object with question, open/closed status, total
voters, answer indexes, answer text, chosen/correct flags, voter counts, and
option_hex tokens. JSON reply_to is null or an object with the replied
message id, peer, thread top id, quote text, quote offsets, reply media kind,
forwarded reply metadata, and a one-level resolved_message when Telegram can
fetch it.
Connector action workflow:
Use ConnectorActionDraft with the send_message connector action for
outbound Telegram messages. This creates a human-reviewable draft and does not
send directly. Pass reply_to or reply_to_message_id with a Telegram message
id to send the outbound message as a reply after approval. To send files,
images, or albums, include media as a path/URL string, an object, or an array.
The message text is the caption for the first attachment unless an attachment
object has its own caption.
{
"to": "123456789",
"message": "done",
"reply_to": 42,
"media": [
{"path": "/tmp/screenshot.png", "kind": "photo", "caption": "result"},
{"path": "/tmp/report.pdf", "kind": "file"}
]
}
Use Telegram-specific connector actions for message edits/deletes/forwards,
pinning, reactions, read state, poll votes, chat membership/admin operations,
account profile updates, group metadata updates, avatars, and stories. These
are ConnectorAct actions on telegram-login when they do not send, forward,
post, or otherwise publish an external message. Send-like actions require the
human-review draft path and must not be called directly with ConnectorAct. Do
not invent a separate Telegram runtime command. Prefer numeric peer ids resolved
by search-peers.
Use the vote_poll connector action to click a poll answer. Prefer answer
indexes from --succinct output or option_hex from JSON output; exact answer
text also works when unambiguous.
{"to": "123456789", "message_id": 77, "option": 0}
Common Telegram action examples:
{"connector_slug": "telegram-login", "connection_slug": "tg-alt", "action": "update_group_title", "input": {"to": "123456789", "title": "New group name"}}
{"connector_slug": "telegram-login", "action": "react", "input": {"to": "123456789", "message_id": 77, "emoji": "<emoji>"}}
{"connector_slug": "telegram-login", "action": "pin_message",
Supported action slugs include vote_poll, edit_message, delete_messages,
forward_messages, pin_message, unpin_message, unpin_all_messages,
react, mark_read, clear_mentions, send_typing, join_chat,
leave_chat, invite_users, kick_participant, ban_participant,
unban_participant, update_profile, update_username, update_avatar,
update_group_title, update_group_name, update_group_username,
update_group_photo, and send_story. Telegram may reject an action if the
account lacks the required admin rights or the peer type does not support it.
Authentication workflow:
For Telegram Desktop import, QR login, phone login, login codes, local
passcodes, and 2FA passwords, route the user through:
/connect telegram-login <connection>
The /connect command asks the user to choose import, QR, or phone login with
AskUserQuestion, gathers any required input there, and calls the typed Telegram
auth helper directly. Do not reproduce the auth flow with Bash or stdin flags
from this skill.
After login or import completes, use the returned connection_slug in
workflows and connector actions when the user wants ongoing monitoring or
outbound side effects.
