guide · 6 min read

Forum mode — one bot, many services

Point snitchbot at a forum-enabled supergroup and it will create one topic per service you pass to init(). Each topic is fed only that service’s events. You get clean separation without spinning up N bots.

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

Step 01 — step :00 · 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 — step :01 · add the bot as admin with topic rights

Promote your bot to administrator and tick Manage Topics. Without that right snitchbot falls back to writing into General with a single warning at startup.

Step 03 — step :02 · 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         (sidecar lifecycle, system messages)
├ 🟠 orders-api      (alerts only for orders-api)
└ 🟣 billing-api     (alerts only for billing-api)

Per-topic commands

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

Choosing the topic colour

Auto-assigned deterministically from service against Telegram’s 7-colour palette. Override per-service:

snitchbot.init(
    "payments",
    token="...",
    chat_id="-1001234567890",
    topic_color=7322096,    # one of: 7322096, 16766590, 13338331,
                            # 9367192, 16749490, 16478047, 7396918
)

Forcing simple mode

Detection is automatic by default. To force simple mode (write into General without topics), pass forum=False:

snitchbot.init("svc", token="...", chat_id="-100...", forum=False)

Troubleshooting

Q: I see one warning about lacking can_manage_topics — what now?

Promote the bot to administrator in the group settings and tick Manage Topics. snitchbot auto-resumes forum behaviour at the next sidecar 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 — snitchbot keys on message_thread_id, not on the topic name. Rename freely.

Q: Can I disable forum mode for one service while others use it?

No — the mode is per-bot, not per-service. To run two services in different modes, use two bots (two tokens, two chat_ids).

What’s next