--- name: Telegram Bot Ops slug: telegram-bot-ops category: Automation description: Telegram Bot Ops helps diagnose, monitor, deploy, and safely restart Telegram bots and Telegram-to-agent gateways. Use it to check webhooks, polling, logs, delivery paths, and runtime health without exposing secrets. github: "https://github.com/serejaris/personal-corp-os/tree/main/skills/tg-bot-ops" language: HTML stars: 224 forks: 25 install: "npx degit https://github.com/serejaris/personal-corp-os/tree/main/skills/tg-bot-ops ~/.claude/skills/tg-bot-ops" installs_to: ~/.claude/skills/tg-bot-ops source_path: skills/tg-bot-ops/SKILL.md collection_size: 25 category_size: 1754 collection_url: "https://dirskills.com/collections/serejaris/personal-corp-os" added: 2026-09-03T06:05:27.527Z last_synced: 2026-09-03T06:05:27.527Z canonical_url: "https://dirskills.com/skills/telegram-bot-ops" --- # Telegram Bot Ops Telegram Bot Ops helps diagnose, monitor, deploy, and safely restart Telegram bots and Telegram-to-agent gateways. Use it to check webhooks, polling, logs, delivery paths, and runtime health without exposing secrets. **Install:** ```bash npx degit https://github.com/serejaris/personal-corp-os/tree/main/skills/tg-bot-ops ~/.claude/skills/tg-bot-ops ``` ## README # Telegram Bot Ops Use this skill when the real question is whether a Telegram bot is receiving updates, processing them in the intended runtime, and sending visible responses to the right chat, user, or forum topic. ## Public Safety - Default to read-only diagnostics. - Do not print tokens, `.env` values, connection strings, raw logs, private DMs, payment payloads, session files, or full user records. - Use placeholders in notes and examples: ``, ``, ``, ``, ``. - Do not send Telegram messages, restart production services, change webhooks, edit BotFather settings, or deploy until the user has authorized that exact action. - If any real secret appears in the repo, logs, or prompt, stop and tell the user it must be rotated before public release. ## Intake If the repo or runtime is unclear, identify: - bot repo and language/runtime; - deployment target: local, Docker, VPS/systemd, Railway, Render, Fly, Vercel, or other; - update mode: webhook, polling, or unknown; - env source for `TELEGRAM_BOT_TOKEN`; - expected symptom, chat surface, and timestamp; - whether production restart/deploy is allowed. ## Diagnostic Flow 1. **Repo and runtime** — inspect entrypoints, process manager, deploy files, and current git state. 2. **Environment** — verify required env var names exist without printing values. 3. **Update intake** — classify runtime: HTTP Bot API webhook, HTTP Bot API polling, MTProto bot session, or MTProto user session. 4. **Bot API identity** — for Bot API-token runtimes, run `getMe` using a masked token path. 5. **Webhook/polling mode** — for Bot API-token runtimes, run `getWebhookInfo` and inspect runtime logs. 6. **Single update owner** — resolve `409 Conflict` by reading the error text: webhook conflict means webhook/deleteWebhook path; competing `getUpdates` means find the polling owner. 7. **Telegram delivery** — use a fresh nonce for Bot API or Telethon/user-session E2E when user-visible behavior matters. 8. **Handler/runtime** — prove the runtime received and processed the update. 9. **Outbound response** — prove the bot sent to the expected chat/topic. 10. **Incident note** — report symptom, evidence, root cause, fix, and residual risk. ## Telegram-To-Agent Gateways When the bot is a gateway from Telegram into an agent runtime, read [references/hermes-gateway.md](references/hermes-gateway.md). The reference is Hermes-compatible but intentionally generic: bot handle, host, service name, home directory, chat ids, topic ids, env paths, and logs must be placeholders or redacted. ## Bot API vs Telethon / MTProto - Bot API is Telegram's HTTP interface for bot tokens: `getUpdates`, webhooks, `sendMessage`, `getMe`, callbacks, payments, and join requests. - Telethon is an MTProto client. It can be a bot-account runtime with `start(bot_token=...)` or a user-session E2E harness for what a Telegram user sees. - Pick one primary intake per bot token/account: Bot API webhook, Bot API polling, MTProto bot session, or MTProto user session. Do not mix without a clear deduplication plan. ## Webhook And Polling Checks Safe read-only checks should avoid putting the token-bearing URL in shell history, process listings, or copied logs. Prefer a tiny local helper: ```python import json, os, urllib.request token = os.environ["TELEGRAM_BOT_TOKEN"] for method in ("getMe", "getWebhookInfo"): with urllib.request.urlopen(f"https://api.telegram.org/bot{token}/{method}") as response: data = json.load(response) print(method, {"ok": data.get("ok"), "result_keys": sorted((data.get("result") or {}).keys())}) ``` Do not paste the token-bearing URL into notes or issues. In reports, write: ```text getWebhookInfo: webhook_url=, pending_update_count=, last_error= ``` Direct `getUpdates` diagnostics can consume pending updates. Use it only with a fresh nonce, short timeout, known update owner, and restore plan. ## Forum Topics And Privacy - Non-General forum topics require preserving `message_thread_id`. - General topic is normally sent like an ordinary supergroup message: omit `message_thread_id`. Preserve `message_thread_id` for non-General topics. - With privacy mode enabled, bots see targeted commands, replies to the bot, inline messages via the bot, service messages, private chats, and channel messages where they are a member. Admin bots can receive all group messages. - Disabling privacy or removing/re-adding a bot affects group visibility and requires explicit user authorization. ## Restart / Deploy Gate Before restarting or deploying: - identify the exact production owner/process; - capture current status and rollback command; - state expected downtime or risk; - confirm the user authorized the action; - run post-restart `getMe`, webhook/polling, and one visible smoke test. ## Output Format Answer with: 1. **Status** — `not checked`, `local only`, `runtime checked`, `verified in Telegram`, or `blocked`. 2. **Evidence** — commands/logs checked, with secrets redacted. 3. **Finding** — the failing layer or confirmed healthy layer. 4. **Action** — what changed or the next safe step. 5. **Public safety** — note if any secret, user data, or private payload was found. ## Anti-Patterns - Claiming "bot works" from unit tests only. - Printing raw bot tokens, `.env`, logs, user messages, payment payloads, or DB rows. - Changing webhook/polling mode without knowing the current production owner. - Running a local polling process with a production token while production is active. - Ignoring `message_thread_id` when the bot lives in Telegram forum topics.