Skip to main content
skill CX Codex

telegram · acedatacloud — Claude Code skill: search messages across chats

Controls a personal Telegram account via Telethon and MTProto. Helps read unread chats, search history, download media, and send messages directly from the agent.

Apache-2.0 189 installs ★ 17 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add AceDataCloud/Skills --skill telegram -a claude-code
Open on GitHub

What telegram does

The skill interacts with Telegram as a user account via MTProto using telethon. Unlike the standard Bot API, the agent sees the full account history. It lists conversations, tracks unread messages, accesses contacts, and views forum topic threads.

All actions run via Bash through the included scripts/tg.py script. Read commands execute immediately. Any mutating action like sending messages, deleting, reacting, or joining channels requires a trailing --confirm flag. Without this flag, the command only runs a dry run.

The tool requires three environment variables: TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING. An expired or invalid session string immediately breaks authentication.

What it helps with

  • summarize unread messages across recent chats
  • download media attachments from a specific conversation
  • send replies, reactions, or files using a personal account
  • post messages into a specific forum topic thread
  • search messages across all personal conversations

Example prompts for the agent

  • Show my unread Telegram chats and summarize the recent messages.
  • Search Telegram messages across all chats for the keyword release.
  • Send a file to the user @alice with a caption and confirm the action.

How to install telegram

1Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill telegram -a claude-code

2Manually: put the files in place

~/.claude/skills/telegram/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/telegram/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about telegram

How to install telegram in Claude Code?

Run npx skills add AceDataCloud/Skills --skill telegram -a claude-code. The skill definition will be saved to ~/.claude/skills/telegram/SKILL.md.

How is this skill different from a standard Telegram bot?

It connects over MTProto and Telethon as a userbot with your personal account credentials. This enables full access to private chat histories, unread lists, and contacts that the standard Bot API cannot reach.

Why do message-sending commands run in dry-run mode by default?

All state-changing actions require an explicit trailing --confirm flag to execute. Without it, the helper only previews the action so you can avoid unintended messages or deletions.

Source text

SKILL.md · Apache-2.0
---
name: telegram
description: Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, list a forum group's topics, download media, and send / reply / forward / edit / delete / react / send files / mark read / join & leave groups, including posting into a forum topic thread. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading/replying/forwarding/summarizing Telegram messages, their unread Telegram, joining or leaving a Telegram group/channel, posting into a forum group's topic, or sending a file/message on Telegram.
when_to_use: |
  Trigger for anything on the user's personal Telegram account: list recent
  conversations or just the unread ones, read / summarize a chat or group,
  search one chat or across all chats, look up a contact or a chat's info,
  download a photo/file from a message, list a forum group's topics, or take an
  action — send, reply, forward, edit, delete, react, send a file, mark a chat
  read, post into a forum topic, or join / leave a group or channel. This drives
  the user's OWN account over MTProto (not a bot), so it sees everything they see.
connections: [telegram]
allowed_tools: [Bash]
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.4"
---

We drive **personal** Telegram over MTProto with [Telethon](https://docs.telethon.dev/) —
this acts as the user's own account (a "userbot"), so unlike the Bot API it can read full
history, list every conversation, and act on anyone the user can reach.

Credentials are injected as env vars by the connector:

- `TELEGRAM_API_ID` — app id
- `TELEGRAM_API_HASH` — app hash — **secret, never echo**
- `TELEGRAM_SESSION_STRING` — Telethon `StringSession` = **full account access. Never log,
  echo, or print it.** Treat it like the account password.

## CLI

The skill ships [`scripts/tg.py`](scripts/tg.py) — self-contained (the only third-party dep is
`telethon`, preinstalled in the sandbox). Point a var at the shipped path and call it; no heredoc
to re-create per turn, so a multi-step flow (dry-run → confirm) can't lose the helper between calls:

```sh
# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block below).
TG="$SKILL_DIR/scripts/tg.py"; [ -f "$TG" ] || TG=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/tg.py' 2>/dev/null | head -1)
[ -f "$TG" ] || { echo "telegram script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$TG" whoami
```

Every state-changing command (`send`, `reply`, `send-file`, `forward`, `edit`, `delete`,
`react`, `mark-read`, `join`, `leave`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
it would do, changes nothing). Read commands run directly. `--confirm` is honored **only as the
last argument** so a message/caption that merely contains "--confirm" can never silently confirm.

## Verify the connection first

```sh
python3 "$TG" whoami
# → {"id": 100000000, "username": "<the connected handle>", "name": "<display name>", "phone": "..."}
```

On an auth/session error the stored session is dead — tell the user to reconnect at
https://studio.acedata.cloud/console/connectors.

## Read recipes

| Goal | Command |
|---|---|
| Recent conversations | `python3 "$TG" list-chats 20` |
| Only chats with unread (ranked) | `python3 "$TG" unread` |
| A chat's history (oldest→newest) | `python3 "$TG" get-messages <target> 50` |
| Search inside one chat | `python3 "$TG" search <target> "kw" 30` |
| Search across ALL chats | `python3 "$TG" search-global "kw" 30` |
| List contacts | `python3 "$TG" contacts` |
| Info about a chat/user | `python3 "$TG" chat-info <target>` |
| List a forum group's topics (threads) | `python3 "$TG" list-topics <target>` |
| t.me link to a message | `python3 "$TG" message-link <target> <msg_id>` |

`<target>` = numeric id (most reliable — from `list-chats`), `@username`, phone, or exact chat
name. In message rows, `out:true` = sent by the user; `media:true` = has an attachment.

**Summarize-unread pattern**: `unread` → pick the chats that matter → `get-messages <id> N` on
each → summarize. Don't dump 20k messages; sample the most-unread / most-relevant.

## Media

```sh
# Download an attachment from a message → returns the saved path
python3 "$TG" download-media <target> <msg_id> ./tg_downloads
# Send a local file OR an http(s) URL (optional caption) — GATED
python3 "$TG" send-file <target> /path/or/https-url "caption" --confirm
```

An `http(s)` URL is downloaded to a real local file first (with the right
extension from the URL / `Content-Type`) and then uploaded, so a remote image
lands as a **photo** — not a document, and not a silent failure. This is the
reliable way to "发图": pass the CDN URL straight to `send-file`.

To hand a downloaded file back to the user as a link, upload it to the CDN (see the
`cos-upload` skill) after `download-media`.

## Write recipes — all GATED (dry-run unless trailing `--confirm`)

Sending/editing/deleting acts as the **real user**. Always run the dry run first, show the user
exactly what will happen, get an explicit "yes", then re-run with `--confirm` as the **last
argument**. Never bulk-send.

```sh
python3 "$TG" send    <target> "text"                          # → dry_run; add --confirm to send
python3 "$TG" send    <target> "text" --topic <top_message> --confirm  # into a forum topic thread
python3 "$TG" reply   <target> <msg_id> "text" --confirm
python3 "$TG" forward <from_target> <msg_id> <to_target> --confirm
python3 "$TG" edit    <target> <msg_id> "new text" --confirm   # own messages
python3 "$TG" delete  <target> <msg_id> --confirm              # destructive
python3 "$TG" react   <target> <msg_id> "👍" --confirm
python3 "$TG" mark-read <target> --confirm                     # sends read receipts
python3 "$TG" join    <@username|t.me/link|t.me/+invite> --confirm  # join a public group/channel or a private invite
python3 "$TG" leave   <target> --confirm                       # leave a group/channel (not private chats)
```

`join` accepts a public `@username` / `t.me/<name>` (→ JoinChannelRequest) or a private
invite link `t.me/+HASH` / `t.me/joinchat/HASH` (→ ImportChatInviteRequest). Joining someone
else's group is a real membership change on the account — treat it like any other write:
dry-run, confirm, then `--confirm`. Never auto-join then bulk-message; that gets accounts
spam-limited.

**Posting into a forum group.** Some supergroups are *forums*: messages live in topics
(threads), and a plain `send` to the group root is rejected with `TOPIC_CLOSED`. Run
`list-topics <target>` first, pick a topic with `"closed": false` (an open chat/offtopic
thread — often titled `Беседка`/`Флуд`/`Chat`/`Offtopic`/`General`), then post with
`send <target> "text" --topic <top_message> --confirm` (its `top_message` id is the thread
anchor).

The dry run returns `{"dry_run": true, "command": ..., "args": [...]}` — present that to the
user verbatim as the confirmation prompt.

## Gotchas — surface before the user is surprised

- **This is the user's real account.** Confirm before any write; reading exposes private chats.
- **`FloodWaitError`**: Telegram rate-limits userbots. On a flood-wait of N seconds, tell the
  user to retry after N — never loop/retry aggressively (escalates toward a ban).
- **Dead session**: revoked from Telegram → Settings → Devices, or ~6-month inactivity. On
  `AuthKeyError`/unauthorized, reconnect the connector (don't retry).
- **Never print `TELEGRAM_SESSION_STRING` / `TELEGRAM_API_HASH`** — full-account secrets.
- **Targets**: prefer the numeric `id` from `list-chats` (the helper recovers its access hash by
  scanning dialogs); names need an exact match, usernames need a leading `@`.
- **`message-link`** only works for public channels/supergroups; private 1:1 / basic groups
  return an error (no shareable link exists).
- **`TOPIC_CLOSED` on send** = a forum supergroup; you can't post to the root. `list-topics`,
  pick an open (`"closed": false`) thread, and `send ... --topic <top_message>`.
- **`ChatWriteForbiddenError` on send** = usually a channel's linked *discussion* group: you
  must be subscribed to the parent channel (`join <parent_channel>`) before you can write in
  its comment group, even though the group itself doesn't ban posting.
- **`edit`/`delete`** generally only apply to the user's own messages (admins can delete others
  in groups they manage).


## Record the output

After you successfully publish and obtain the live result URL, call the built-in
`publish_artifact` tool ONCE so the user can track this deliverable in **My Outputs**:

```
publish_artifact(kind="message", channel="telegram", title="<title>", url="<the REAL returned URL>", status="delivered")
```

Use the real returned URL — never fabricate one. Call it once per published item,
only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
See `_shared/artifacts.md`.

© acedatacloud · Apache-2.0 · AceDataCloud/Skills

Similar skills

All skills for Telegram bots →

telegram by other authors comes first.

telegram glebis Fetches, searches and sends Telegram messages, downloads attachments, edits sent messages. Works via telegram_dl and Telegram API. CX Codex +1 287installs telegram skillhq Hands your coding agent a Telegram CLI: read chats, search across them, reply, moderate groups and export history to files. CX Codex +1 486installs telegram membrane Skill for Telegram integration through Membrane. Manage chats, messages, and users; automate workflows without direct API calls or token management. CX Codex +1 189installs Better Telegram MCP n24q02m Better Telegram MCP is an MCP server that connects an agent to Telegram messages, chats, media, and contacts, through either a bot or a regular account. CX Codex +1 ★ 12repo stars telegram-mcp jgalea Wires your own Telegram account into an AI agent so it can read chats, search history, send replies and pull down media without you opening the app. CX Codex +1 ★ 7repo stars tg-ws-proxy-telegram-socks5 reason-machines tg-ws-proxy-telegram-socks5 guides the setup of a local SOCKS5 proxy routing Telegram Desktop traffic to data centers over WebSockets. Useful for bypassing connection blocks without remote servers. CX Codex +1 889installs claude-ops-telegram-server Lifecycle-Innovations-Limited claude-ops-telegram-server connects a personal Telegram account to your coding agent via MTProto. Lets assistants read private direct messages, search conversation history, and send replies. CX Codex +1 ★ 557repo stars fast-mcp-telegram leshchenko1979 fast-mcp-telegram is an MCP server for Claude Code that connects an AI agent to Telegram with 8 tools, QR sign-in, and HTTP access to MTProto. CX Codex +1 ★ 50repo stars WireCat Telegram WireCatLabs WireCat Telegram — an MCP server that gives agents access to your whole Telegram account: local message search, sending, checking unread messages and group chats. CX Codex +1 ★ 19repo stars

From the same set67

The whole set →

More in the catalog

Project sponsors

Companies that keep this analytics open