#2703: docs(groups): clarify groupAllowFrom vs groups config
docs
## What
Clarifies the distinction between `groupAllowFrom` (sender allowlist) and `groups` (group allowlist) in the groups documentation.
## Why
We spent a debugging session chasing a "bug" where WhatsApp group messages silently stopped working after a restart. Turned out we'd put a group JID in `groupAllowFrom` — which expects phone numbers/user IDs. The field name is ambiguous enough that `groupAllowFrom` reads naturally as "allow from these groups".
Filed as [#1952](https://github.com/clawdbot/clawdbot/issues/1952) before we identified the real cause.
## Changes
- **TL;DR section**: Split vague "group access" bullet into three clear ones (which groups, which senders, policy mode). Added ⚠️ callout.
- **Quick-reference table**: Added "(phone numbers, not group IDs)" clarification and new "anyone can trigger" row. Added "Common mistake" callout box.
- **Evaluation order**: Expanded from 3 vague steps to 4 explicit steps with descriptions.
- **Group policy notes**: Clarified `groupAllowFrom` is a sender filter with ⚠️ warning.
## AI-assisted 🤖
Written with Claude (via Clawdbot). The misconfiguration was experienced first-hand and the docs changes were verified against the actual access-control code in `src/web/inbound/access-control.ts`.
Lightly tested (docs-only change, no code changes).
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates `docs/concepts/groups.md` to clarify the distinction between `groups` (which group/room IDs are allowed) and `groupAllowFrom` (which senders are allowed to trigger inside groups), and expands the docs’ “quick reference” and “evaluation order” sections accordingly.
The main thing to double-check is internal consistency with the actual enforcement path: the “Quick flow” diagram text doesn’t include the sender allowlist step, and some examples imply `groupAllowFrom` applies on its own, even though the WhatsApp access-control implementation only consults it when `groupPolicy: "allowlist"`. The mental model also introduces a `groups` check that may be enforced outside the shown access-control layer; adding a pointer to where that happens would prevent confusion.
<h3>Confidence Score: 4/5</h3>
- This is safe to merge; it’s a docs-only change with a few likely-to-confuse inconsistencies to tighten.
- No code paths are modified. The flagged issues are documentation accuracy/consistency problems (missing sender-allowlist step in the quick flow, examples that may imply behavior not matching current enforcement, and an evaluation-order step that may be enforced elsewhere).
- docs/concepts/groups.md
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#11611: feat: separate group-level allowlist from sender-level command auth...
by thisnick · 2026-02-08
86.3%
#5665: fix: match group JIDs in groupAllowFrom allowlist
by koala73 · 2026-01-31
82.3%
#6567: fix: include paired users in WhatsApp group sender allowlist
by giannisanni · 2026-02-01
81.3%
#4402: fix: store group messages from non-allowlisted senders as pending c...
by adam91holt · 2026-01-30
79.5%
#4390: fix(whatsapp): allow media from allowlisted groups without groupAllow…
by Sarang19114 · 2026-01-30
79.5%
#4337: fix(signal): add group-level allowlist support via groups config
by derekross · 2026-01-30
77.4%
#23288: feat(whatsapp): group command gating via commands.allowFrom + sende...
by rodrigoscoelho · 2026-02-22
75.9%
#18664: fix(imessage): honor groupConfig regardless of allowlistEnabled
by brandonwise · 2026-02-16
75.2%
#12818: docs(messages): clarify message tool ordering vs inline replies
by JBrady · 2026-02-09
74.7%
#10894: Docs: fix legacy branding, add config reference, expand cron troubl...
by biv0711 · 2026-02-07
74.5%