Telegram Send

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

# превью (ничего не отправляет):
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 (apiid, apihash, 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
• Source: dewil/claude-toolkit
• License: MIT

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