Group Messages

WhatsApp group message handling behavior and configuration. mentionPatterns are shared across all interfaces (CLI, TUI, Web UI).

This page focuses on WhatsApp-specific group message handling behavior, including activation modes, history context injection, and mention gating.

WhatsApp groups support two activation modes:

- ''mention'' (default): Only trigger replies when @mentioned or when matching mentionPatterns.

- ''always'': Trigger replies for all group messages (not recommended for public groups).

Configuration:

- Global: ''channels.whatsapp.groupPolicy = mention|always''

- Per-group: ''channels.whatsapp.groups.<jid>.requireMention = false'' (set to false for always mode)

mentionPatterns is an array of regular expressions used to match text in group messages, triggering replies even without @mentions.

{ "messages": { "groupChat": { "mentionPatterns": [ "^(?i)\\b(bot|assistant|help|ai)\\b", "^@openclaw", "^(?i)\\b(hey|hello|hi)\\s+openclaw" ] } } }

Can also be overridden per agent:

''agents.list[].groupChat.mentionPatterns''

When group messages don't trigger a reply (no mention / blocked by allowlist), OpenClaw stores these messages as pending.

On the next trigger, these pending messages are injected into the prompt as context to help the model understand conversation history.

This ensures that even if the bot doesn't reply to every message, it can still keep up with the latest discussions in the group.

When a group message triggers a reply, OpenClaw injects recent history messages into the prompt.

History messages are divided into two parts:

- Pending messages: Messages since the last reply that weren't processed (up to historyLimit).

- Transcript messages: Historical messages that have been written to the session record.

Main configuration options for WhatsApp group message handling:

- ''channels.whatsapp.groupPolicy'': Global activation mode (mention/always).

- ''channels.whatsapp.groups.<jid>.requireMention'': Override activation mode per group.

- ''channels.whatsapp.historyLimit'': Maximum number of pending history messages (default 50).

Some channels support the ''/activation'' command (affects current session only):

- ''/activation mention'': Requires mention (default).

- ''/activation always'': Reply to all messages.

Note: This command typically only works for authorized senders (owner/allowlist). To persist behavior, write configuration instead of relying on session commands.