guide · 5 min read

Per-service topics — one bot, many services

Point snitchbot at a forum-enabled supergroup and the sidecar creates one topic per service you pass to init(). Each topic is fed only that service’s alerts; commands sent inside a topic scope to that service. You get clean separation without running N bots.

Works withNeedsSince
Telegram supergroup with Topics enabledsnitchbot ≥ 0.2.0, bot is admin with Manage Topics0.2.0

There is no manual switch. The sidecar checks the chat once at startup; if the chat is a forum and the bot has can_manage_topics, per-service topics are activated. Otherwise every message goes to the chat without a thread id.

Step 01 — turn the group into a forum

In Telegram, open group settings → Topics → enable. (Owner-only; irreversible while topics exist.) The “General” topic appears automatically.

Step 02 — add the bot as admin with topic rights

Promote your bot to administrator and tick Manage Topics. Without that right the sidecar logs a single info line at startup and writes everything to the chat without topics — nothing crashes.

Step 03 — point services at the same chat_id

# orders-api
import snitchbot
snitchbot.init("orders-api", token="...", chat_id="-1001234567890")

# billing-api
snitchbot.init("billing-api", token="...", chat_id="-1001234567890")

The first event from each service auto-creates a topic named after the service. Subsequent runs reuse the topic — the mapping is persisted under ~/.snitchbot/topics-<config_hash>.json.

What the chat looks like

Three topics in one supergroup, each a clean stream of one service’s alerts:

Topics
├ 🟢 General         (system fallback)
├ 🟠 orders-api      (alerts + lifecycle + dashboard for orders-api)
└ 🟣 billing-api     (alerts + lifecycle + dashboard for billing-api)

Topic colours are auto-derived deterministically from the service name against Telegram’s 7-colour palette. They are stable across restarts.

Per-topic commands

/status, /last, /chart, /mute, /export sent inside a topic scope to that topic’s service, and the bot replies in the same topic. The same command in General returns the global summary across all services.

Troubleshooting

Q: I see an info line about lacking can_manage_topics — what now?

Promote the bot to administrator in the group settings and tick Manage Topics. The sidecar picks the change up on the next restart.

Q: I deleted a topic by hand — will snitchbot break?

No. The next send detects message thread not found, drops the cached mapping, recreates the topic, and retries the send once.

Q: Can I rename a topic?

Yes — the sidecar keys on message_thread_id, not on the topic name. Rename freely.

Q: Can I run different services with different routing?

Routing is per-chat, not per-service. To split services across separate streams, use separate chats (and separate bot tokens if you need separate command surfaces).

What’s next