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.
1---2name: tg-bot-publish3description: "Публикация в Telegram через бота (Bot API, tg_bot.py): посты в канал, рассылка, кнопки. Триггеры: «пост в канал от бота»."4keywords: telegram bot api, tg_bot.py, sendRichMessage, пост в канал от бота, бот админ канала, кнопка к посту, rich пост таблица, рассылка подписчикам, sendMessage, inline keyboard, broadcast, paid media stars, инвайт ссылка, вебхук, getFile, опрос от бота5metadata:6 source: https://skillmd.com/skills/jhamidun/tg-bot-publish7---89# TG Bot Publish — публикация и управление через бота (Bot API)1011Операционный навык: как **публиковать и управлять** в Telegram через бота напрямую по Bot API.12Инструмент — единый CLI `~/.claude/tools/tg_bot.py` (Python + requests, без зависимостей кроме requests).1314> Это НЕ копирайтинг (текст поста пишет [[tg-post]]) и НЕ разработка бота (см. `telegram-bot-toolkit`).15> Это «у меня есть бот-токен — опубликуй/разошли/настрой».1617## Главный принцип1819В Bot API **нет разницы между «в канал» и «подписчику в личку»** — везде один `chat_id` (`--to`):20- **канал** → `@username` или `-100<id>` (бот должен быть **админом** с правом *Post Messages*)21- **подписчик** → его `<user_id>` (бот пишет только если юзер сам нажал `/start`)22- **рассылка** → подкоманда CLI `broadcast` по списку2324Один инструмент покрывает оба сценария — меняется только `--to`.2526## Токены2728`--token` принимает сам токен (`123:ABC…`) ИЛИ **своё короткое имя бота**, которое резолвится29из `~/.claude/.credentials.master.env` (шаблон: `~/.claude/templates/.credentials.master.env.example`).30Имя ищется в четырёх видах: `BOT_TOKEN_<ИМЯ>`, `TELEGRAM_BOT_TOKEN_<ИМЯ>`,31`<ИМЯ>_TELEGRAM_BOT_TOKEN`, `<ИМЯ>`. Никакого встроенного реестра ботов нет — имя придумываешь ты:3233```bash34# в ~/.claude/.credentials.master.env35BOT_TOKEN_MYBOT=123456:AAH… # → --token MYBOT36BOT_TOKEN_SALESBOT=987654:AAG… # → --token SALESBOT37```3839Несколько ботов держи под разными именами: у бота-админа канала и бота для личек обычно40разные права, и перепутанный токен даёт не ошибку, а пост не в тот канал.41Проверка перед первой отправкой — `me`: отвечает именем бота, значит токен резолвится.4243Глобальный `--dry-run` печатает payload и НЕ отправляет — всегда проверяй им перед боевой отправкой.4445## Базовые сценарии4647```bash48# проверить токен49python ~/.claude/tools/tg_bot.py --token MYBOT me5051# ── ПОСТ В КАНАЛ (бот-админ) ──52# текст + форматирование + раскрывающийся блок + кнопка-переход на пост53python ~/.claude/tools/tg_bot.py --token MYBOT send --to @yourchannel \54 --text "<b>Заголовок</b>55<blockquote expandable>скрытый длинный текст</blockquote>" \56 --btn "Открыть пост|https://t.me/your_username/123" --pin5758# фото-пост, спойлер, подпись над фото, две кнопки в ряд59python ~/.claude/tools/tg_bot.py --token MYBOT send --to @yourchannel --photo cover.jpg \60 --text "Подпись" --spoiler --caption-above \61 --btn-row "Сайт|https://your-domain.com ;; Промокод|copy:AI2026"6263# ── RICH-ПОСТ (Bot API 10.1): таблицы / заголовки / картинки в посте ──64python ~/.claude/tools/tg_bot.py --token MYBOT rich --to @yourchannel --md-file post.md65# (rich_message = {"markdown": "..."} — Telegram сам парсит markdown в блоки)6667# ── ПОДПИСЧИКУ В ЛИЧКУ / РАССЫЛКА ──68python ~/.claude/tools/tg_bot.py --token SALESBOT send --to 123456789 --text "Личное сообщение"69python ~/.claude/tools/tg_bot.py --token SALESBOT updates --out subs.txt # собрать chat_id70python ~/.claude/tools/tg_bot.py --token SALESBOT --dry-run broadcast --to-file subs.txt \71 --text "<b>Анонс</b> 👇" --btn "Регистрация|https://your-domain.com/conf"72```7374## Карта команд (163 — ПОЛНОЕ покрытие Bot API, 173/173 метода)7576| Группа | Команды |77|---|---|78| Контент/цикл | `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` |79| Админка канала | `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` |80| Инвайты/заявки | `invite-create/edit/revoke/export join-approve join-decline sub-invite-create sub-invite-edit post-approve post-decline` |81| Монетизация (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` |82| Стикер-сеты | `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` |83| Профили ботов флота | `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` |84| Форум-топики | `forum-create/edit/close/reopen/delete/unpin-all forum-icons gen-edit/close/reopen/hide/unhide` |85| Бизнес-аккаунт + истории | `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` |86| Файлы/разведка | `get-file user-photos user-audios` |87| Вебхуки/сервер | `webhook-set webhook-delete webhook-info logout close-bot managed-get managed-set` |88| Верификация/игры | `verify-user verify-chat unverify-user unverify-chat send-game game-score game-scores` |89| 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` |90| Rich-стриминг/inline | `rich-draft prep-inline` |9192`python ~/.claude/tools/tg_bot.py --help` — полный список; у каждой подкоманды свой `--help`.93Большинство команд из реестра — обёртки над одним методом Bot API; структурные параметры передаются JSON-аргументом (`--stickers '[...]'`, `--content '{...}'`, `--results '[...]'`).9495## Форматирование (HTML, по умолчанию в `send`)9697`<b> <i> <u> <s>` · `<tg-spoiler>` · `<code> <pre>` · `<blockquote>` / **`<blockquote expandable>`** (раскрывающийся блок) · `<a href>` · `<tg-emoji>`.9899## Кнопки (`--btn "Текст|значение"`, ряд — `--btn-row "A|… ;; B|…"`)100101`url`(http/tg) · `copy:текст` · `app:url`(web-app) · `switch:` · `switchcur:` · `cb:`(callback — оживает только при запущенном боте, см. `listen`). **В канале работают URL/copy/app**; callback — для интерактива в личке.102103## Ключевые грабли104105- Юзеру нельзя написать первым — только после его `/start` (иначе 403).106- `getUpdates`/`listen` ⟂ webhook: при активном вебхуке апдейтов нет → диагностика `webhook-info`, снять `webhook-delete`.107- Кнопку нельзя пришить к посту, опубликованному руками — только к посту, отправленному ботом.108- Rich: лимит 32768 символов; `<details>`+формула роняет Telegram Desktop; CJK искажается; рендерится только в ботах/каналах с ботом-админом.109- `forwardMessages`/`copyMessages` — id строго по возрастанию, до 100; `sendPaidMedia` — 1–25000 Stars; `rich-draft` — только личка + ненулевой draft_id.110- JSON-аргументы для структур: `--media`(InputPaidMedia[]) `--prices`(LabeledPrice[]) `--perms`(ChatPermissions) `--commands`(BotCommand[]) `--button`(MenuButton) `--result`(InlineQueryResult).111112## Справочники (progressive disclosure)113114- **`~/.claude/tools/TG_BOT_API_REFERENCE.md`** (~270 КБ) — детальный справочник всех **173 методов**115 Bot API: назначение, версия, все параметры, что возвращает, грабли; у каждого метода помечено,116 покрыт ли он CLI-командой. Сюда смотреть, когда нужен точный параметр метода.117 Читать выборочно (`grep -n "<метод>"` → нужный раздел), а не целиком: файл в контекст не влезет.118119## Границы (что НЕ через этот навык)120121- Текст/копирайтинг поста → [[tg-post]] (потом опубликовать готовое — этим навыком).122- Разработка интерактивного бота с нуля (handlers, scenes, deploy) → `telegram-bot-toolkit`.123- Чтение истории, парсинг участников, действия от ЛИЧНОГО аккаунта → `~/.claude/tools/tg_client.py` (Telethon, user-API — кнопки слать НЕ может).124- Публикация через сторонний планировщик соцсетей (сразу в несколько площадок, отложка) → `postiz`, `publora-post`.125- Вне скоупа CLI (есть в REFERENCE, но не зашиты): создание стикер-сетов, бизнес-аккаунты, passport, forum-топики CRUD, live-хендлеры платежей/inline.