← Back to PRs

#2703: docs(groups): clarify groupAllowFrom vs groups config

by RichardFellows open 2026-01-27 09:45 View on GitHub →
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