JHamidun TG Bot Publish — публикация и управление через бота (Bot API)
Операционный навык: как публиковать и управлять в Telegram через бота напрямую по Bot API.
Инструмент — единый CLI ~/.claude/tools/tg_bot.py (Python + requests, без зависимостей кроме requests).
Это НЕ копирайтинг (текст поста пишет [[tg-post]]) и НЕ разработка бота (см.
telegram-bot-toolkit). Это «у меня есть бот-токен — опубликуй/разошли/настрой».
Главный принцип
В Bot API нет разницы между «в канал» и «подписчику в личку» — везде один chat_id (--to):
- канал →
@usernameили-100<id>(бот должен быть админом с правом Post Messages) - подписчик → его
<user_id>(бот пишет только если юзер сам нажал/start) - рассылка → подкоманда CLI
broadcastпо списку
Один инструмент покрывает оба сценария — меняется только --to.
Токены
--token принимает сам токен (123:ABC…) ИЛИ своё короткое имя бота, которое резолвится
из ~/.claude/.credentials.master.env (шаблон: ~/.claude/templates/.credentials.master.env.example).
Имя ищется в четырёх видах: BOT_TOKEN_<ИМЯ>, TELEGRAM_BOT_TOKEN_<ИМЯ>,
<ИМЯ>_TELEGRAM_BOT_TOKEN, <ИМЯ>. Никакого встроенного реестра ботов нет — имя придумываешь ты:
# в ~/.claude/.credentials.master.env
BOT_TOKEN_MYBOT=123456:AAH… # → --token MYBOT
BOT_TOKEN_SALESBOT=987654:AAG… # → --token SALESBOT
Несколько ботов держи под разными именами: у бота-админа канала и бота для личек обычно
разные права, и перепутанный токен даёт не ошибку, а пост не в тот канал.
Проверка перед первой отправкой — me: отвечает именем бота, значит токен резолвится.
Глобальный --dry-run печатает payload и НЕ отправляет — всегда проверяй им перед боевой отправкой.
Базовые сценарии
# проверить токен
python ~/.claude/tools/tg_bot.py --token MYBOT me
# ── ПОСТ В КАНАЛ (бот-админ) ──
# текст + форматирование + раскрывающийся блок + кнопка-переход на пост
python ~/.claude/tools/tg_bot.py --token MYBOT send --to @yourchannel \
--text "<b>Заголовок</b>
<blockquote expandable>скрытый длинный текст</blockquote>" \
--btn "Открыть пост|https://t.me/your_username/123" --pin
# фото-пост, спойлер, подпись над фото, две кнопки в ряд
python ~/.claude/tools/tg_bot.py --token MYBOT send --to @yourchannel --photo cover.jpg \
--text "Подпись" --spoiler --caption-above \
--btn-row "Сайт|https://your-domain.com ;; Промокод|copy:AI2026"
# ── RICH-ПОСТ (Bot API 10.1): таблицы / заголовки / картинки в посте ──
python ~/.claude/tools/tg_bot.py --token MYBOT rich --to @yourchannel --md-file post.md
# (rich_message = {"markdown": "..."} — Telegram сам парсит markdown в блоки)
# ── ПОДПИСЧИКУ В ЛИЧКУ / РАССЫЛКА ──
python ~/.claude/tools/tg_bot.py --token SALESBOT send --to 123456789 --text "Личное сообщение"
python ~/.claude/tools/tg_bot.py --token SALESBOT updates --out subs.txt # собрать chat_id
python ~/.claude/tools/tg_bot.py --token SALESBOT --dry-run broadcast --to-file subs.txt \
--text "<b>Анонс</b> 👇" --btn "Регистрация|https://your-domain.com/conf"
Карта команд (163 — ПОЛНОЕ покрытие Bot API, 173/173 метода)
| Группа | Команды |
|---|---|
| Контент/цикл | send rich album poll dice location contact venue live-photo edit edit-media pin unpin unpin-all react react-del react-clear copy copy-batch forward forward-batch delete stop-poll action broadcast updates link listen |
| Админка канала | admins count member ban unban restrict promote perms set-title set-desc set-photo set-admin-title ban-channel unban-channel set-member-tag del-photo leave user-boosts |
| Инвайты/заявки | invite-create/edit/revoke/export join-approve join-decline sub-invite-create sub-invite-edit post-approve post-decline |
| Монетизация (Stars) | invoice invoice-link paid-media gift gifts star-balance star-tx refund star-sub gift-premium user-gifts chat-gifts gift-convert gift-upgrade gift-transfer |
| Стикер-сеты | sticker-upload stickerset-create sticker-add sticker-pos sticker-del sticker-replace sticker-emojis sticker-keywords sticker-mask stickerset-title stickerset-thumb emoji-set-thumb stickerset-del stickerset-get custom-emoji set-chat-stickers del-chat-stickers |
| Профили ботов флота | set-name get-name set-bot-desc get-bot-desc set-bot-short get-bot-short get-commands del-commands menu-button get-menu-button set-default-rights get-default-rights set-bot-photo del-bot-photo set-commands |
| Форум-топики | forum-create/edit/close/reopen/delete/unpin-all forum-icons gen-edit/close/reopen/hide/unhide |
| Бизнес-аккаунт + истории | biz-get biz-read biz-delete biz-set-name/username/bio/photo biz-del-photo biz-gift-settings biz-star-balance biz-transfer-stars biz-gifts story-post/edit/delete send-checklist edit-checklist |
| Файлы/разведка | get-file user-photos user-audios |
| Вебхуки/сервер | webhook-set webhook-delete webhook-info logout close-bot managed-get managed-set |
| Верификация/игры | verify-user verify-chat unverify-user unverify-chat send-game game-score game-scores |
Live-хендлеры (нужен свежий *_query_id из listen/webhook) |
answer-inline answer-webapp answer-shipping answer-precheckout answer-guest answer-joinreq-query join-webapp save-kbd-button msg-draft edit-live-loc stop-live-loc |
| Rich-стриминг/inline | rich-draft prep-inline |
python ~/.claude/tools/tg_bot.py --help — полный список; у каждой подкоманды свой --help.
Большинство команд из реестра — обёртки над одним методом Bot API; структурные параметры передаются JSON-аргументом (--stickers '[...]', --content '{...}', --results '[...]').
Форматирование (HTML, по умолчанию в send)
<b> <i> <u> <s> · <tg-spoiler> · <code> <pre> · <blockquote> / <blockquote expandable> (раскрывающийся блок) · <a href> · <tg-emoji>.
Кнопки (--btn "Текст|значение", ряд — --btn-row "A|… ;; B|…")
url(http/tg) · copy:текст · app:url(web-app) · switch: · switchcur: · cb:(callback — оживает только при запущенном боте, см. listen). В канале работают URL/copy/app; callback — для интерактива в личке.
Ключевые грабли
- Юзеру нельзя написать первым — только после его
/start(иначе 403). getUpdates/listen⟂ webhook: при активном вебхуке апдейтов нет → диагностикаwebhook-info, снятьwebhook-delete.- Кнопку нельзя пришить к посту, опубликованному руками — только к посту, отправленному ботом.
- Rich: лимит 32768 символов;
<details>+формула роняет Telegram Desktop; CJK искажается; рендерится только в ботах/каналах с ботом-админом. forwardMessages/copyMessages— id строго по возрастанию, до 100;sendPaidMedia— 1–25000 Stars;rich-draft— только личка + ненулевой draft_id.- JSON-аргументы для структур:
--media(InputPaidMedia[])--prices(LabeledPrice[])--perms(ChatPermissions)--commands(BotCommand[])--button(MenuButton)--result(InlineQueryResult).
Справочники (progressive disclosure)
~/.claude/tools/TG_BOT_API_REFERENCE.md(~270 КБ) — детальный справочник всех 173 методов Bot API: назначение, версия, все параметры, что возвращает, грабли; у каждого метода помечено, покрыт ли он CLI-командой. Сюда смотреть, когда нужен точный параметр метода. Читать выборочно (grep -n "<метод>"→ нужный раздел), а не целиком: файл в контекст не влезет.
Границы (что НЕ через этот навык)
- Текст/копирайтинг поста → [[tg-post]] (потом опубликовать готовое — этим навыком).
- Разработка интерактивного бота с нуля (handlers, scenes, deploy) →
telegram-bot-toolkit. - Чтение истории, парсинг участников, действия от ЛИЧНОГО аккаунта →
~/.claude/tools/tg_client.py(Telethon, user-API — кнопки слать НЕ может). - Публикация через сторонний планировщик соцсетей (сразу в несколько площадок, отложка) →
postiz,publora-post. - Вне скоупа CLI (есть в REFERENCE, но не зашиты): создание стикер-сетов, бизнес-аккаунты, passport, forum-топики CRUD, live-хендлеры платежей/inline.