WhatsApp (canal web)¶

Statut : WhatsApp Web via Baileys uniquement. La Gateway (passerelle) possède la/les session(s).

Default DM policy is pairing for unknown senders. Cross-channel diagnostics and repair playbooks. Full channel config patterns and examples.

Carte rapide de configuration¶

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

openclaw channels login --channel whatsapp

```
For a specific account:
```

openclaw channels login --channel whatsapp --account work

openclaw gateway

Approuver avec : `openclaw pairing approve whatsapp <code>` (liste avec `openclaw pairing list whatsapp`).

```
Les codes expirent après 1 heure ; les demandes en attente sont plafonnées à 3 par canal.
```

Idéal pour garder votre WhatsApp personnel séparé — installez WhatsApp Business et enregistrez-y le numéro OpenClaw. (The channel metadata and onboarding flow are optimized for that setup, but personal-number setups are also supported.)

Deployment patterns¶

This is the cleanest operational mode:

```
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
```

Onboarding supports personal-number mode and writes a self-chat-friendly baseline:

```
{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}
```

The messaging platform channel is WhatsApp Web-based (Baileys) in current OpenClaw channel architecture.

```
There is no separate Twilio WhatsApp messaging channel in the built-in chat-channel registry.
```

Runtime model¶

Gateway owns the WhatsApp socket and reconnect loop.
Outbound sends require an active WhatsApp listener for the target account.
Status and broadcast chats are ignored (@status, @broadcast).
Direct chats use DM session rules (session.dmScope; default main collapses DMs to the agent main session).
Les groupes correspondent à des sessions agent:<agentId>:whatsapp:group:<jid>.

Access control and activation¶

Politique de messages privés : channels.whatsapp.dmPolicy contrôle l’accès aux discussions directes (par défaut : pairing).

```
`channels.whatsapp.dmPolicy` (politique DM : appairage/liste d’autorisation/ouvert/désactivé).
```

Group access has two layers:

```
`channels.whatsapp.groups` (liste d’autorisation de groupe + valeurs par défaut de filtrage par mention ; utilisez `"*"` pour autoriser tout).
```

Group replies require mention by default.

```
Mention detection includes:

- explicit WhatsApp mentions of the bot identity
- configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- implicit reply-to-bot detection (reply sender matches bot identity)

Session-level activation command:

- `/activation mention`
- `/activation always`

`activation` updates session state (not global config). It is owner-gated.
```

Personal-number and self-chat behavior¶

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

skip read receipts for self-chat turns
ignore mention-JID auto-trigger behavior that would otherwise ping yourself
Les réponses en auto‑discussion utilisent par défaut [{identity.name}] lorsque défini (sinon [openclaw]) si messages.responsePrefix n’est pas défini.

Normalisation des messages (ce que voit le modèle)¶

Incoming WhatsApp messages are wrapped in the shared inbound envelope.

````
If a quoted reply exists, context is appended in this form:

```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```

Reply metadata fields are also populated when available (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
````

Les messages entrants contenant uniquement des médias utilisent des espaces réservés :

```
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`

Location and contact payloads are normalized into textual context before routing.
```

For groups, unprocessed messages can be buffered and injected as context when the bot is finally triggered.

```
Les messages récents _non traités_ (50 par défaut) sont insérés sous :
`[Chat messages since your last reply - for context]` (les messages déjà présents dans la session ne sont pas réinjectés)
```

Par défaut, la Gateway marque les messages WhatsApp entrants comme lus (coches bleues) une fois acceptés.

```
{
  channels: {
    whatsapp: {
      accounts: {
        personal: { sendReadReceipts: false },
      },
    },
  },
}
```

Delivery, chunking, and media¶

Découpage optionnel par saut de ligne : définissez channels.whatsapp.chunkMode="newline" pour découper sur les lignes vides (limites de paragraphes) avant le découpage par longueur.

- supports image, video, audio (PTT voice-note), and document payloads - audio/ogg is rewritten to audio/ogg; codecs=opus for voice-note compatibility - animated GIF playback is supported via gifPlayback: true on video sends - captions are applied to the first media item when sending multi-media reply payloads - media source can be HTTP(S), file://, or local paths

- inbound media save cap: channels.whatsapp.mediaMaxMb (default 50) - outbound media cap for auto-replies: agents.defaults.mediaMaxMb (default 5MB) - images are auto-optimized (resize/quality sweep) to fit limits - on media send failure, first-item fallback sends text warning instead of dropping the response silently

Acknowledgment reactions¶

channels.whatsapp.ackReaction (auto‑réaction à la réception des messages : {emoji, direct, group}).

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Remarques :

sent immediately after inbound is accepted (pre-reply)
failures are logged but do not block normal reply delivery
group mode mentions reacts on mention-triggered turns; group activation always acts as bypass for this check
WhatsApp ignore messages.ackReaction ; utilisez channels.whatsapp.ackReaction à la place.

Multi-account and credentials¶

channels.whatsapp.accounts.<accountId> .* (paramètres par compte + authDir optionnel).

Configurez WhatsApp dans ~/.openclaw/openclaw.json.Identifiants stockés dans ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.

Connexion multi‑comptes : openclaw channels login --account <id> (<id> = accountId).]` clears WhatsApp auth state for that account.

```
In legacy auth directories, `oauth.json` is preserved while Baileys auth files are removed.
```

Tools, actions, and config writes¶

Agent tool support includes WhatsApp reaction action (react).
Action gates:
channels.whatsapp.actions.reactions (verrouiller les réactions d’outil WhatsApp).
channels.whatsapp.groupPolicy (politique de groupe).
{ channels: { whatsapp: { configWrites: false } }, }

Troubleshooting¶

Symptôme : channels status affiche linked: false ou avertit « Not linked ».

```
Déconnexion : `openclaw channels logout` (ou `--account <id>`) supprime l’état d’authentification WhatsApp (mais conserve le `oauth.json` partagé).
```

Symptom: linked account with repeated disconnects or reconnect attempts.

```
Correctif : `openclaw doctor` (ou redémarrez la Gateway). Si le problème persiste, reliez via `channels login` et inspectez `openclaw logs --follow`.
```

Outbound sends fail fast when no active gateway listener exists for the target account.

```
Make sure gateway is running and the account is linked.
```

Check in this order:

```
Politique de groupe : `channels.whatsapp.groupPolicy = open|disabled|allowlist` (par défaut `allowlist`).
```

WhatsApp gateway runtime should use Node. WhatsApp (Baileys) et Telegram sont peu fiables avec Bun. Exécutez la Gateway avec Node.

Configuration reference pointers¶

Primary reference:

Configuration reference - WhatsApp

High-signal WhatsApp fields:

access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
multi-account: accounts.<id>.enabled, accounts.<id>.authDir, account-level overrides
operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
session behavior: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>messages.groupChat.historyLimit`

Pairing
Channel routing
Guide de dépannage : Gateway troubleshooting.

Configuration