let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify group chat behavior

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-10 19:56:43 +01:00
parent 7947059884
commit 831de9ba8f
2 changed files with 101 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/concepts/groups.md
View File

@@ -7,6 +7,37 @@ read_when:
Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage.
## Beginner intro (2 minutes)
Clawdbot “lives” on your own messaging accounts. There is no separate WhatsApp bot user.
If **you** are in a group, Clawdbot can see that group and respond there.
Default behavior:
- Groups are allowed (`groupPolicy: "open"`).
- Replies require a mention unless you explicitly disable mention gating.
Translation: anyone in the group can trigger Clawdbot by mentioning it.
> TL;DR
> - **DM access** is controlled by `*.allowFrom`.
> - **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
> - **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).
Quick flow (what happens to a group message):
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
If you want...
| Goal | What to set |
|------|-------------|
| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` |
| Disable all group replies | `groupPolicy: "disabled"` |
| Only specific groups | `groups: { "<group-id>": { ... } }` (no `"*"` key) |
| Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## 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.
@@ -65,6 +96,11 @@ Notes:
- Group DMs are controlled separately (`discord.dm.*`, `slack.dm.*`).
- Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
Quick mental model (evaluation order for group messages):
1) `groupPolicy` (open/disabled/allowlist)
2) group allowlists (`*.groups`, `*.groupAllowFrom`, provider-specific allowlist)
3) mention gating (`requireMention`, `/activation`)
## Mention gating (default)
Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
@@ -113,6 +149,47 @@ Notes:
## Group allowlists
When `whatsapp.groups`, `telegram.groups`, or `imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior.
Common intents (copy/paste):
1) Disable all group replies
```json5
{
whatsapp: { groupPolicy: "disabled" }
}
```
2) Allow only specific groups (WhatsApp)
```json5
{
whatsapp: {
groups: {
"123@g.us": { requireMention: true },
"456@g.us": { requireMention: false }
}
}
}
```
3) Allow all groups but require mention (explicit)
```json5
{
whatsapp: {
groups: { "*": { requireMention: true } }
}
}
```
4) Only the owner can trigger in groups (WhatsApp)
```json5
{
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
groups: { "*": { requireMention: true } }
}
}
```
## Activation (owner-only)
Group owners can toggle per-group activation:
- `/activation mention`

24
docs/start/faq.md
View File

@@ -273,6 +273,30 @@ This runs your login shell and imports only missing expected keys (never overrid
Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).
### Do I need to add a “bot account” to a WhatsApp group?
No. Clawdbot runs on **your own account**, so if you’re in the group, Clawdbot can see it.
By default, anyone in that group can **mention** the bot to trigger a reply.
If you want only **you** to be able to trigger group replies:
```json5
{
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"]
}
}
```
### Why doesn’t Clawdbot reply in a group?
Two common causes:
- Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
- You configured `whatsapp.groups` without `"*"` and the group isn’t allowlisted.
See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
### Do groups/threads share context with DMs?
Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).