izackp/takopi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(telegram): topics scope + thread-aware replies (#81)

Browse Source
This commit is contained in:
banteg
2026-01-11 01:40:49 +04:00
committed by GitHub
parent 94fda5e7e6
commit 77504231d4
11 changed files with 300 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/transports/telegram.md
+10 -7
View File
@@ -44,21 +44,24 @@ Configuration (under `[transports.telegram]`):
```toml
[transports.telegram.topics]
enabled = true
mode = "multi_project_chat" # or "per_project_chat"
scope = "auto" # auto | main | projects | all
```
Requirements:
- `multi_project_chat`: `chat_id` must be a forum-enabled supergroup (topics enabled).
- `per_project_chat`: each `projects.<alias>.chat_id` must point to a forum-enabled
- `main`: `chat_id` must be a forum-enabled supergroup (topics enabled).
- `projects`: each `projects.<alias>.chat_id` must point to a forum-enabled
supergroup for that project.
- `all`: both the main chat and each project chat must be forum-enabled.
- `auto`: if any project chats are configured, uses `projects`; otherwise `main`.
- The bot needs the **Manage Topics** permission in the relevant chat(s).
Commands:
- `multi_project_chat`: `/topic <project> @branch` creates a topic in the main chat
and binds it.
- `per_project_chat`: `/topic @branch` creates a topic in the project chat and binds it.
- `main`: `/topic <project> @branch` creates a topic in the main chat and binds it.
- `projects`: `/topic @branch` creates a topic in the project chat and binds it.
- `all`: use `/topic <project> @branch` in the main chat, or `/topic @branch` in
project chats.
- `/ctx` inside a topic shows the bound context and stored session engines.
`/ctx set ...` and `/ctx clear` update the binding.
- `/new` inside a topic clears stored resume tokens for that topic.
@@ -66,7 +69,7 @@ Commands:
State is stored in `telegram_topics_state.json` alongside the config file.
Delete it to reset all topic bindings and stored sessions.
Note: `multi_project_chat` does not assume a default project; topics must be bound
Note: main chat topics do not assume a default project; topics must be bound
before running without directives.
## Outbox model
docs/user-guide.md
+11 -10
View File
@@ -238,14 +238,14 @@ Topics bind Telegram forum threads to specific project/branch contexts. They als
```toml
[transports.telegram.topics]
enabled = true
mode = "multi_project_chat" # or "per_project_chat"
```
Your bot needs **Manage Topics** permission in the group.
### Topic modes explained
If any `projects.<alias>.chat_id` are configured, topics are managed in those
project chats; otherwise topics are managed in the main chat.
**`multi_project_chat`** — One forum-enabled supergroup for everything. Create topics per project/branch combination.
### Topic behavior
```
┌────────────────────────────┐
@@ -258,7 +258,10 @@ Your bot needs **Manage Topics** permission in the group.
└────────────────────────────┘
```
**`per_project_chat`** — Each project has its own forum-enabled supergroup. Topics still include the project name for consistency, but the project is inferred from the chat. Regular messages in that chat also infer the project, so `/project` is usually optional.
Each project can have its own forum-enabled supergroup. Topics still
include the project name for consistency, but the project is inferred from the
chat. Regular messages in that chat also infer the project, so `/project` is
usually optional.
```
┌────────────────────────────────┐ ┌───────────────────────────────────┐
@@ -282,11 +285,11 @@ Run these inside a topic thread:
| `/ctx clear` | Remove the binding |
| `/new` | Clear resume tokens for this topic |
In `per_project_chat` mode, omit the project: `/topic @branch` or `/ctx set @branch`.
In project chats, omit the project: `/topic @branch` or `/ctx set @branch`.
### Configuration examples
**Multi-project chat:**
**Main chat only:**
```toml
[transports.telegram]
@@ -294,10 +297,9 @@ chat_id = -1001234567890
[transports.telegram.topics]
enabled = true
mode = "multi_project_chat"
```
**Per-project chat:**
**Project chats:**
```toml
[transports.telegram]
@@ -305,7 +307,6 @@ chat_id = 123456789 # main chat (private, for non-project messages)
[transports.telegram.topics]
enabled = true
mode = "per_project_chat"
[projects.takopi]
path = "~/dev/takopi"
@@ -350,7 +351,7 @@ voice_transcription = true
[transports.telegram.topics]
enabled = true
mode = "multi_project_chat"
scope = "auto"
# Project definitions
[projects.takopi]