# Telegram Send

> Отправить сообщение в Telegram-чат проекта от имени пользователя (личка или группа) через scripts/telegram-send.py. Использовать когда пользователь говорит "напиши в телеграм", "отправь сообщение в чат X", "напиши <чат> в телеге", "отпиши в чат от моего имени", "скинь в группу <текст>". НЕ для чтения истории чатов - это telegram-snapshot.

- **Type:** Skill
- **Install:** `agentstack add skill-dewil-claude-toolkit-telegram-send`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dewil](https://agentstack.voostack.com/s/dewil)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dewil](https://github.com/dewil)
- **Source:** https://github.com/dewil/claude-toolkit/tree/main/skills/telegram-send

## Install

```sh
agentstack add skill-dewil-claude-toolkit-telegram-send
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# telegram-send

Скилл для отправки сообщения в Telegram-чат проекта **от имени пользователя**. Личка и группа отправляются одинаково. Скрипт-эталон - `scripts/telegram-send.py` (top-level папка `scripts/` в корне проекта). Авторизация общая с `telegram-snapshot` (`~/.config/telegram-snapshot/auth.json` + `.session`), адресаты берутся из `.telegram-snapshot.json`.

## Когда применять

- Пользователь просит написать/отправить/скинуть сообщение в один из чатов проекта от своего имени.
- Нужно ответить в конкретную форумную тему или реплаем на сообщение.

## Когда НЕ применять

- Чтение/анализ истории чатов - это `telegram-snapshot` (`result.json` уже на диске, читай напрямую).
- Адресата нет в `.telegram-snapshot.json` - сначала добавить его туда (см. ниже), отдельного механизма отправки "куда угодно" у скрипта нет.

## Обязательный гейт отправки

Отправка в Telegram **необратима и видна другому человеку**. Поэтому всегда:

1. **Dry-run.** Запусти `scripts/telegram-send.py` БЕЗ `--send`. Скрипт зарезолвит адресата и напечатает заголовок чата, id, тему/реплай и полный текст - но ничего не отправит.
2. **Покажи пользователю** результат dry-run: в какой именно чат (по заголовку, а не только label) и **текст дословно**, как он уйдет.
3. **Дождись явного "ок".** Без подтверждения - не отправлять. Это конкретизация канон-принципа "audit -> ок -> action" для внешнего необратимого действия.
4. **Только потом** запусти ту же команду с `--send`.

Никогда не запускай `--send` без показанного пользователю dry-run и явного согласия. Молчаливое согласие ("ну напиши что-нибудь") - не основание отправлять не показав текст.

## Как составлять текст

- От первого лица, как сам пользователь, в его тоне. Это его сообщение, не твое.
- Коротко и по делу; не дописывай вежливых хвостов и пояснений от себя.
- Не добавляй подпись "отправлено через..." и подобное.
- Если пользователь продиктовал текст дословно - отправляй дословно, не переписывай.
- Перед отправкой показываешь ровно тот текст, что уйдет (никаких "примерно так").

## CLI

```bash
# превью (ничего не отправляет):
python3 scripts/telegram-send.py --to "с командой" --text "Привет, созвон в 15:00"

# реальная отправка (после "ок"):
python3 scripts/telegram-send.py --to "с командой" --text "Привет, созвон в 15:00" --send

# многострочный текст - через stdin:
python3 scripts/telegram-send.py --to "с командой" --send ` (обязательный) - label чата из `.telegram-snapshot.json -> chats`. Если label нет - скрипт печатает список доступных и выходит.
- `--text ` - текст. Если опущен, читается из stdin (удобно для многострочного).
- `--send` - реально отправить. Без него - dry-run.
- `--topic ` - id корня форумной темы. Если не задан, но у label в конфиге расширенная запись с `topic_id` - берется он (так сообщение в форум-чат уходит в нужную тему, а не в General).
- `--reply-to ` - id сообщения, на которое отвечаем.

`--reply-to` отвечает на сообщение и кладет ответ в тему этого сообщения автоматически; `--topic` нужен для постинга нового сообщения в тему без реплая. Если задать оба, приоритет у `--reply-to` (тема берется из отвечаемого сообщения, `--topic` игнорируется) - high-level API Telethon не умеет одновременно reply на сообщение и явный topic.

## Адресаты только из конфига

Скрипт шлет строго в чаты, перечисленные в `.telegram-snapshot.json`. Это намеренное ограничение - предсказуемость и защита от отправки не туда.

Чтобы написать в новый чат, сначала добавь его label в `.telegram-snapshot.json -> chats` (формат записи и как узнать `chat_id` - см. скилл `telegram-snapshot`, шаг 6). После этого `--to ` заработает.

### Single-chat-by-id: адресат вне конфига

Для сценариев, где адресата в общий конфиг класть нельзя (разовый чат, клиент трека поддержки - его чат не должен попадать в ежедневные pull/дельты), есть драйвер `scripts/telegram-send-one.py` - явное исключение из правила выше:

```bash
# dry-run (по умолчанию), id прямо в командной строке:
python3 scripts/telegram-send-one.py  [expected_username] --text "..."
# реальная отправка (после "ок"):
python3 scripts/telegram-send-one.py  [expected_username] --text "..." --send
```

Тот же гейт dry-run/`--send`, что у основного скрипта. Вместо защиты "только из конфига" - опциональная сверка `expected_username`: если username чата не совпал с ожидаемым, отправка прерывается (страховка от "не туда"). Флаг `--html` включает HTML-форматирование (жирный/код/ссылки); HTML, а не MarkdownV2 - тот требует экранировать точки/дефисы/скобки, на русском тексте это грабли. Симметричный pull одного чата по id - `scripts/telegram-pull-one.py` (см. скилл `telegram-snapshot`).

## Авторизация

Та же, что у `telegram-snapshot`: `~/.config/telegram-snapshot/auth.json` (api_id, api_hash, session_name) + общая `.session`. Отдельной настройки для отправки не нужно - если snapshot уже работает на устройстве, работает и send. При проблемах с авторизацией/сессией (`AuthKeyUnregisteredError`, PeerUser-ошибки, нет auth.json) - см. скилл `telegram-snapshot`.

## Жесткие правила

1. **Без dry-run и явного "ок" - не отправлять.** Всегда показать пользователю заголовок чата и текст дословно перед `--send`.
2. **Только чаты из `.telegram-snapshot.json`** - либо `telegram-send-one.py` со сверкой `expected_username` для адресата вне конфига (см. "Single-chat-by-id"). Нет label и не single-chat-сценарий - не отправлять, предложить добавить в конфиг.
3. **Текст - от имени пользователя, дословно по согласованию.** Не переписывать продиктованное, не дописывать от себя.
4. **Auth и .session - не в проектной папке.** Только `~/.config/telegram-snapshot/` (см. `telegram-snapshot`).

## Связанные файлы

- `scripts/telegram-send.py` в корне проекта - эталонный скрипт отправки (dry-run по умолчанию, `--send` для реальной отправки).
- `scripts/telegram-send-one.py` - драйвер single-chat-by-id: отправка в один чат по id, минуя конфиг (тот же гейт, сверка username, `--html`). Переиспользует логику telegram-send.py через импорт.
- `.telegram-snapshot.json` в корне проекта - справочник адресатов `{label: chat_id}` (общий со snapshot/deltas).
- `~/.config/telegram-snapshot/auth.json` + `.session` - общая авторизация на устройство.
- Скилл `telegram-snapshot` - первичная настройка авторизации и подключение чатов в конфиг.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dewil](https://github.com/dewil)
- **Source:** [dewil/claude-toolkit](https://github.com/dewil/claude-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dewil-claude-toolkit-telegram-send
- Seller: https://agentstack.voostack.com/s/dewil
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.