fix(telegram): support forum topics

Co-authored-by: Daniel Griesser <HazAT@users.noreply.github.com>
Co-authored-by: Nacho Iacovino <nachoiacovino@users.noreply.github.com>
Co-authored-by: Randy Ventures <RandyVentures@users.noreply.github.com>

docs/concepts/groups.md

@@ -9,6 +9,7 @@ Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Di
 
 ## Session keys
 - Group sessions use `agent:<agentId>:<provider>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+- Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.
 - Direct chats use the main session (or per-sender if configured).
 - Heartbeats are skipped for group sessions.
 
@@ -118,6 +119,7 @@ Group inbound payloads set:
 - `GroupSubject` (if known)
 - `GroupMembers` (if known)
 - `WasMentioned` (mention gating result)
+- Telegram forum topics also include `MessageThreadId` and `IsForum`.
 
 The agent system prompt includes a group intro on the first turn of a new group session.
 

docs/concepts/provider-routing.md

@@ -16,6 +16,7 @@ Goal: deterministic replies per provider, while supporting multi-agent + multi-a
 - **Canonical direct session (per agent):** direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`). Groups/channels stay isolated per agent:
   - group: `agent:<agentId>:<provider>:group:<id>`
   - channel/room: `agent:<agentId>:<provider>:channel:<id>`
+  - Telegram forum topics: `agent:<agentId>:telegram:group:<chatId>:topic:<threadId>`
 - **Session store:** per-agent store lives under `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (override via `session.store` with `{agentId}` templating). JSONL transcripts live next to it.
 - **WebChat:** attaches to the selected agent’s main session (so desktop reflects cross-provider history for that agent).
 - **Implementation hints:**

docs/concepts/session.md

@@ -25,6 +25,7 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl
 - Direct chats collapse to the per-agent primary key: `agent:<agentId>:<mainKey>`.
   - Multiple phone numbers and providers can map to the same agent main key; they act as transports into one conversation.
 - Group chats isolate state: `agent:<agentId>:<provider>:group:<id>` (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
+  - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
   - Legacy `group:<id>` keys are still recognized for migration.
 - Other sources:
   - Cron jobs: `cron:<job.id>`

docs/providers/telegram.md

@@ -38,6 +38,12 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
 - Group replies require a mention by default (native @mention or `routing.groupChat.mentionPatterns`).
 - Replies always route back to the same Telegram chat.
 
+## Topics (forum supergroups)
+Telegram forum topics include a `message_thread_id` per message. Clawdbot:
+- Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
+- Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
+- Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
+
 ## Access control (DMs + groups)
 - Default: `telegram.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved.
 - Approve via: