<Step title="Incoming message arrives">

A WhatsApp group or DM message arrives.

</Step>

<Step title="Route and admission">

OpenClaw applies channel allowlists, group activation rules, and configured ACP binding ownership.

</Step>

<Step title="Broadcast check">

System checks if peer ID is in `broadcast`.

If no configured ACP binding owns the route, OpenClaw checks whether the peer ID is in `broadcast`.

</Step>

<Step title="If in broadcast list">

<Step title="If broadcast applies">

- All listed agents process the message.

- Each agent has its own session key and isolated context.

- Agents process in parallel (default) or sequentially.

</Step>

<Step title="If not in broadcast list">

Normal routing applies (first matching binding).

<Step title="If broadcast does not apply">

OpenClaw dispatches the ordinary route or the configured ACP session route selected during routing.

</Step>

</Steps>

- `GROUP_B`: agent1 AND agent2 respond (broadcast).

<Note>

**Precedence:** `broadcast` takes priority over `bindings`.

**Precedence:** `broadcast` takes priority over ordinary route bindings. Configured ACP bindings (`bindings[].type="acp"`) are exclusive: when one matches, OpenClaw dispatches to the configured ACP session instead of fan-out broadcast.

</Note>

## Troubleshooting

</Accordion>

<Accordion title="Only one agent responding">

**Cause:** Peer ID might be in `bindings` but not `broadcast`.

**Cause:** Peer ID might be in ordinary route bindings but not `broadcast`, or it might match an exclusive configured ACP binding.

**Fix:** Add to broadcast config or remove from bindings.

**Fix:** Add ordinary route-bound peers to broadcast config, or remove/change the configured ACP binding if fan-out broadcast is desired.

</Accordion>

<Accordion title="Performance issues">

</Tab>

</Tabs>

## Configured ACP bindings

WhatsApp supports persistent ACP bindings with top-level `bindings[]` entries:

```json5

{

bindings: [

{

type: "acp",

agentId: "codex",

match: {

channel: "whatsapp",

accountId: "work",

peer: { kind: "direct", id: "+15555550123" },

},

},

{

type: "acp",

agentId: "codex",

match: {

channel: "whatsapp",

accountId: "work",

peer: { kind: "group", id: "120363424282127706@g.us" },

},

},

],

}

```

- Direct chats match E.164 numbers such as `+15555550123`.

- Groups match WhatsApp group JIDs such as `120363424282127706@g.us`.

- Group allowlists, sender policy, and mention or activation gating run before OpenClaw ensures the configured ACP session exists.

- A matched configured ACP binding owns the route. WhatsApp broadcast groups do not fan out that turn to ordinary WhatsApp sessions.

## Personal-number and self-chat behavior

When the linked self number is also present in `allowFrom`, WhatsApp self-chat safeguards activate:

}

```

- Top-level `bindings[]` entries with `type: "acp"` configure persistent ACP bindings for WhatsApp DMs and groups. Use an E.164 direct number or WhatsApp group JID in `match.peer.id`. Field semantics are shared in [ACP Agents](/tools/acp-agents#persistent-channel-bindings).

<Accordion title="Multi-account WhatsApp">

```json5

- **Discord channel/thread:** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`

- **Slack channel/DM:** `match.channel="slack"` + `match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"`. Prefer stable Slack ids; channel bindings also match replies inside that channel's threads.

- **Telegram forum topic:** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`

- **WhatsApp DM/group:** `match.channel="whatsapp"` + `match.peer.id="<E.164|group JID>"`. Use E.164 numbers such as `+15555550123` for direct chats and WhatsApp group JIDs such as `120363424282127706@g.us` for groups.

- **iMessage DM/group:** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`. Prefer `chat_id:*` for stable group bindings.

</ParamField>

### Behavior

- OpenClaw ensures the configured ACP session exists before use.

- Messages in that channel or topic route to the configured ACP session.

- OpenClaw ensures the configured ACP session exists after channel-specific admission and before use.

- Messages in that channel, topic, or chat route to the configured ACP session.

- Configured ACP bindings own their session route. Channel broadcast fan-out does not replace the configured ACP session for a matched binding.

- In bound conversations, `/new` and `/reset` reset the same ACP session key in place.

- Temporary runtime bindings (for example created by thread-focus flows) still apply where present.

- For cross-agent ACP spawns without an explicit `cwd`, OpenClaw inherits the target agent workspace from agent config.