# Group Messages

This documentation covers WhatsApp group chat functionality for Clawd, enabling the agent to participate in groups while remaining dormant until activated.

## Key Features

### Activation Modes

The system supports two modes:
- `mention` (default): requires @-ping to respond
- `always`: responds to every message

### Group Policy Control

Access is managed through `groupPolicy` settings with three options:
- `open`
- `disabled`
- `allowlist` (default)

The default `allowlist` blocks messages until senders are explicitly permitted.

### Separate Sessions

Each group maintains its own session context independent from direct messages. Session keys look like `agent:<agentId>:whatsapp:group:<jid>` to keep group and DM conversations isolated.

### Context Injection

Unread group messages (up to 50 by default) are automatically included in prompts, labeled as "[Chat messages since your last reply - for context]" with the current message marked separately.

### Sender Attribution

Each message batch includes `[from: Sender Name (+E164)]` so the agent knows who is speaking.

## Configuration

The setup requires adding mention patterns and group settings to `openclaw.json`, including regex patterns for display-name recognition and numerical fallbacks.

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}
```

## Usage

Simply @-mention the bot in a group (using `@openclaw` or the phone number), and only allowlisted senders can trigger responses unless open policy is enabled. Group-specific commands like `/verbose on` apply only to that session.