К основному содержанию
скилл CX Codex

telegram · acedatacloud — скилл для Claude Code: поиск сообщений в переписках

Управляет личным аккаунтом Telegram через Telethon и MTProto. Помогает читать непрочитанные сообщения, искать переписки, скачивать медиа и отправлять ответы.

Apache-2.0 189 установок ★ 17 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add AceDataCloud/Skills --skill telegram -a claude-code
Открыть на GitHub

Что делает telegram

Скилл работает с Telegram как юзербот через библиотеку telethon и протокол MTProto. В отличие от стандартного Bot API, агент получает доступ ко всей истории личного аккаунта: видит список диалогов, непрочитанные чаты, контакты и ветки в супергруппах-форумах.

Для взаимодействия используется Bash и готовый CLI-скрипт scripts/tg.py. Команды чтения выполняются сразу. Любые действия с изменением состояния требуют явного ключа --confirm в самом конце строки вызова. Без него скрипт ничего не изменит, а лишь покажет dry-run в терминале.

Для запуска нужны переменные окружения TELEGRAM_API_ID, TELEGRAM_API_HASH и TELEGRAM_SESSION_STRING. Без валидной сессии в TELEGRAM_SESSION_STRING скрипт завершится с ошибкой авторизации.

Какие задачи решает

  • найти и прочитать непрочитанные сообщения в чатах
  • скачать медиафайлы или вложения из переписки
  • отправить сообщение, ответ или реакцию от имени личного аккаунта
  • опубликовать пост в конкретную ветку супергруппы-форума
  • найти сообщение по ключевому слову среди всех диалогов

Примеры запросов агенту

  • Покажи непрочитанные сообщения в моих чатах Telegram и сделай краткую выжимку.
  • Найди в Telegram сообщения с ключевым словом релиз и скачай вложенный файл.
  • Отправь сообщение в топик форума Telegram с подтверждением.

Как установить telegram

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/telegram/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о telegram

Как установить telegram в Claude Code?

Выполните команду npx skills add AceDataCloud/Skills --skill telegram -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/telegram/SKILL.md.

Чем этот скилл отличается от обычного Telegram-бота?

Скилл подключается через MTProto и Telethon напрямую к вашей учётной записи как юзербот. Это даёт доступ к полной истории переписок, личным чатам и спискам контактов, чего стандартный Bot API не позволяет.

Почему команды отправки сообщений выполняются в режиме dry-run?

Любые действия, изменяющие состояние аккаунта, требуют флага --confirm на конце команды. Это предотвращает случайную отправку, удаление или редактирование сообщений без предварительной проверки.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Telegram-боты» →

Сначала — telegram от других авторов.

telegram glebis Читает, ищет и отправляет сообщения в Telegram, скачивает вложения, редактирует отправленное. Работает через telegram_dl и API Telegram. CX Codex +1 287установок telegram skillhq Даёт агенту доступ к Telegram: читать переписку, искать по чатам, отвечать, чистить группы и выгружать историю в файлы. CX Codex +1 486установок telegram membrane Скилл для интеграции с Telegram через Membrane. Позволяет управлять чатами, сообщениями и пользователями, автоматизировать рабочие процессы без прямой работы с API и хранения токенов. CX Codex +1 189установок Better Telegram MCP n24q02m MCP-сервер Better Telegram MCP даёт агенту доступ к Telegram: сообщения, чаты, медиа и контакты. Работает и от бота, и от обычного аккаунта. CX Codex +1 ★ 12звёзд репо telegram-mcp jgalea Подключает ваш личный аккаунт Telegram к ИИ-агенту: читать чаты, искать сообщения, отправлять ответы и скачивать медиа прямо из диалога с ассистентом. CX Codex +1 ★ 7звёзд репо tg-ws-proxy-telegram-socks5 reason-machines Скилл tg-ws-proxy-telegram-socks5 помогает настроить локальный SOCKS5-прокси для Telegram Desktop с туннелированием трафика в дата-центры через WebSocket. Пригодится при сетевых блокировках мессенджера. CX Codex +1 889установок claude-ops-telegram-server Lifecycle-Innovations-Limited MCP-сервер claude-ops-telegram-server подключает личный аккаунт Telegram к ассистенту через MTProto. Помогает разбирать входящие личные сообщения, искать переписки и отвечать в чатах. CX Codex +1 ★ 557звёзд репо fast-mcp-telegram leshchenko1979 fast-mcp-telegram — MCP-сервер для Claude Code, который связывает ИИ-агента с Telegram через 8 инструментов, вход по QR-коду и HTTP-доступ к MTProto. CX Codex +1 ★ 50звёзд репо WireCat Telegram WireCatLabs MCP-сервер WireCat Telegram, который открывает агенту весь аккаунт Telegram: поиск по сообщениям на компьютере, отправка, проверка непрочитанного и групповых чатов. CX Codex +1 ★ 19звёзд репо

Из того же набора67

Весь набор →
reddit Ищет обсуждения на Reddit, читает правила сабреддитов, отвечает и публикует посты. Работает с тредами и профилем через OAuth или cookies. CX Codex +1 212установок cos-upload Скилл cos-upload загружает локальные файлы в CDN AceData Cloud и возвращает публичную ссылку для передачи в другие API. CX Codex +1 211установок substack Скилл ведёт ваш настоящий аккаунт Substack через логин-куки: показывает основную публикацию, выгружает посты со статистикой и публикует новый материал. CX Codex +1 207установок discord Интегрирует аккаунт Discord с ИИ-агентом: читает профиль и список серверов по OAuth либо отправляет сообщения через токен пользователя. CX Codex +1 189установок google-search-console Скилл тянет данные Google Search Console через API v1: запросы, страницы, CTR, позиции, сайты, карты сайта и проверку индексации. CX Codex +1 188установок microsoft-excel Читает и правит рабочие книги Excel в OneDrive и SharePoint через Microsoft Graph: диапазоны, таблицы, листы. Токен нужен в $MICROSOFT_EXCEL_TOKEN. CX Codex +1 187установок microsoft-todo Скилл даёт агенту читать и менять списки и задачи Microsoft To Do через Microsoft Graph v1.0 — запросами curl с разбором ответа в jq. CX Codex +1 187установок csdn Управляет блогом на CSDN через личные куки: собирает статистику статей и публикует Markdown-тексты прямо из агента. CX Codex +1 184установок

Ещё в каталоге

Спонсоры проекта

Компании, которые помогают держать аналитику открытой