WhatsApp (canal Web)

Statut : pret pour la production via WhatsApp Web (Baileys). La gateway possede la ou les sessions liees.

• Appairage — La politique DM par defaut est l’appairage pour les expediteurs inconnus.
• Depannage des canaux — Diagnostics multi-canaux et guides de reparation.
• Configuration de la gateway — Patrons et exemples complets de configuration de canal.

Configuration rapide

Etape 1 : Configurer la politique d’acces WhatsApp

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

Etape 2 : Lier WhatsApp (QR)

openclaw channels login --channel whatsapp

Pour un compte specifique :

openclaw channels login --channel whatsapp --account work

Etape 3 : Demarrer la gateway

openclaw gateway

Etape 4 : Approuver la premiere demande d’appairage (en mode appairage)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Les demandes d'appairage expirent apres 1 heure. Les demandes en attente sont plafonnees a 3 par canal.

Remarque : OpenClaw recommande d’utiliser WhatsApp sur un numero separe dans la mesure du possible. (Les metadonnees du canal et le flux d’accueil sont optimises pour cette configuration, mais l’utilisation d’un numero personnel est egalement prise en charge.)

Patrons de deploiement

C'est le mode operationnel le plus propre :

- identite WhatsApp separee pour OpenClaw
- listes d'autorisation DM et limites de routage plus claires
- risque reduit de confusion liee au chat personnel

Patron de politique minimal :

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

L'accueil prend en charge le mode numero personnel et ecrit une base compatible avec le chat personnel :

- `dmPolicy: "allowlist"`
- `allowFrom` inclut votre numero personnel
- `selfChatMode: true`

A l'execution, les protections de chat personnel s'appuient sur le numero personnel lie et `allowFrom`.

Le canal de la plateforme de messagerie est base sur WhatsApp Web (`Baileys`) dans l'architecture actuelle des canaux OpenClaw.

Il n'existe pas de canal de messagerie Twilio WhatsApp distinct dans le registre de canaux integre.

Modele d’execution

• La gateway possede le socket WhatsApp et la boucle de reconnexion.
• Les envois sortants necessitent un ecouteur WhatsApp actif pour le compte cible.
• Les chats de statut et de diffusion sont ignores (@status, @broadcast).
• Les chats directs utilisent les regles de session DM (session.dmScope ; par defaut main regroupe les DMs dans la session principale de l’agent).
• Les sessions de groupe sont isolees (agent:<agentId>:whatsapp:group:<jid>).

Controle d’acces et activation

Politique DM

`channels.whatsapp.dmPolicy` controle l'acces aux chats directs :

- `pairing` (par defaut)
- `allowlist`
- `open` (necessite que `allowFrom` inclue `"*"`)
- `disabled`

`allowFrom` accepte des numeros au format E.164 (normalises en interne).

Surcharge multi-comptes : `channels.whatsapp.accounts.<id>.dmPolicy` (et `allowFrom`) ont priorite sur les valeurs par defaut du canal pour ce compte.

Details du comportement a l'execution :

- les appairages sont persistes dans le store d'autorisation du canal et fusionnes avec le `allowFrom` configure
- si aucune liste d'autorisation n'est configuree, le numero personnel lie est autorise par defaut
- les DMs sortants `fromMe` ne sont jamais appairies automatiquement

Politique de groupe + listes d’autorisation

L'acces aux groupes comporte deux couches :

1. **Liste d'autorisation d'appartenance au groupe** (`channels.whatsapp.groups`)
   - si `groups` est omis, tous les groupes sont eligibles
   - si `groups` est present, il agit comme une liste d'autorisation de groupes (`"*"` autorise)

2. **Politique d'expediteur de groupe** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
   - `open` : la liste d'autorisation des expediteurs est contournee
   - `allowlist` : l'expediteur doit correspondre a `groupAllowFrom` (ou `*`)
   - `disabled` : bloquer tous les messages entrants de groupe

Repli de la liste d'autorisation des expediteurs :

- si `groupAllowFrom` n'est pas defini, l'execution se replie sur `allowFrom` lorsqu'il est disponible
- les listes d'autorisation d'expediteurs sont evaluees avant l'activation par mention/reponse

Remarque : si aucun bloc `channels.whatsapp` n'existe du tout, le repli de la politique de groupe a l'execution est `allowlist` (avec un avertissement dans les logs), meme si `channels.defaults.groupPolicy` est defini.

Mentions + /activation

Les reponses de groupe necessitent une mention par defaut.

La detection de mention inclut :

- les mentions WhatsApp explicites de l'identite du bot
- les patrons regex de mention configures (`agents.list[].groupChat.mentionPatterns`, repli `messages.groupChat.mentionPatterns`)
- la detection implicite de reponse au bot (l'expediteur de la reponse correspond a l'identite du bot)

Note de securite :

- la citation/reponse satisfait uniquement la verification de mention ; elle n'accorde **pas** l'autorisation de l'expediteur
- avec `groupPolicy: "allowlist"`, les expediteurs hors liste sont toujours bloques meme s'ils repondent au message d'un utilisateur autorise

Commande d'activation au niveau de la session :

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

`activation` met a jour l'etat de la session (pas la configuration globale). Elle est reservee au proprietaire.

Comportement du numero personnel et du chat personnel

Lorsque le numero personnel lie est egalement present dans allowFrom, les protections de chat personnel WhatsApp s’activent :

• les accuses de lecture sont ignores pour les tours de chat personnel
• le comportement de declenchement automatique par mention-JID qui vous pinguerait vous-meme est ignore
• si messages.responsePrefix n’est pas defini, les reponses en chat personnel utilisent par defaut [{identity.name}] ou [openclaw]

Normalisation des messages et contexte

Les messages WhatsApp entrants sont encapsules dans l'enveloppe entrante partagee.

Si une reponse citee existe, le contexte est ajoute sous cette forme :

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

Les champs de metadonnees de reponse sont egalement renseignes lorsqu'ils sont disponibles (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 de l'expediteur).

Les messages entrants contenant uniquement des medias sont normalises avec des placeholders tels que :

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

Les donnees de localisation et de contact sont normalisees en contexte textuel avant le routage.

Pour les groupes, les messages non traites peuvent etre mis en tampon et injectes comme contexte lorsque le bot est finalement declenche.

- limite par defaut : `50`
- configuration : `channels.whatsapp.historyLimit`
- repli : `messages.groupChat.historyLimit`
- `0` desactive

Marqueurs d'injection :

- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`

Les accuses de lecture sont actives par defaut pour les messages WhatsApp entrants acceptes.

Desactivation globale :

```json5
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
```

Surcharge par compte :

```json5
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
```

Les tours de chat personnel ignorent les accuses de lecture meme lorsqu'ils sont actives globalement.

Livraison, decoupage et medias

- limite de decoupage par defaut : `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- le mode `newline` privilegie les limites de paragraphe (lignes vides), puis se replie sur le decoupage par longueur

- prend en charge les contenus image, video, audio (note vocale PTT) et document
- `audio/ogg` est reecrit en `audio/ogg; codecs=opus` pour la compatibilite des notes vocales
- la lecture de GIF animes est prise en charge via `gifPlayback: true` sur les envois video
- les legendes sont appliquees au premier element media lors de l'envoi de reponses multi-medias
- la source media peut etre HTTP(S), `file://` ou des chemins locaux

- plafond de sauvegarde des medias entrants : `channels.whatsapp.mediaMaxMb` (par defaut `50`)
- plafond d'envoi des medias sortants : `channels.whatsapp.mediaMaxMb` (par defaut `50`)
- surcharges par compte : `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- les images sont auto-optimisees (redimensionnement/balayage de qualite) pour respecter les limites
- en cas d'echec d'envoi media, le repli du premier element envoie un avertissement textuel au lieu de supprimer la reponse silencieusement

Reactions d’acquittement

WhatsApp prend en charge les reactions d’acquittement immediat a la reception des messages entrants via channels.whatsapp.ackReaction.

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Notes de comportement :

• envoyees immediatement apres l’acceptation du message entrant (avant la reponse)
• les echecs sont journalises mais ne bloquent pas la livraison normale de la reponse
• le mode de groupe mentions reagit aux tours declenches par mention ; l’activation de groupe always contourne cette verification
• WhatsApp utilise channels.whatsapp.ackReaction (l’ancien messages.ackReaction n’est pas utilise ici)

Multi-comptes et identifiants

- les identifiants de compte proviennent de `channels.whatsapp.accounts`
- selection de compte par defaut : `default` s'il est present, sinon le premier identifiant de compte configure (trie)
- les identifiants de compte sont normalises en interne pour la recherche

- chemin d'authentification actuel : `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- fichier de sauvegarde : `creds.json.bak`
- l'authentification historique par defaut dans `~/.openclaw/credentials/` est toujours reconnue/migree pour les flux de compte par defaut

`openclaw channels logout --channel whatsapp [--account <id>]` efface l'etat d'authentification WhatsApp pour ce compte.

Dans les repertoires d'authentification historiques, `oauth.json` est preserve tandis que les fichiers d'authentification Baileys sont supprimes.

Outils, actions et ecritures de configuration

• La prise en charge des outils de l’agent inclut l’action de reaction WhatsApp (react).
• Verrous d’action :
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Les ecritures de configuration initiees par le canal sont activees par defaut (desactivez via channels.whatsapp.configWrites=false).

Depannage

Symptome : le statut du canal indique non lie.

Correction :

```bash
openclaw channels login --channel whatsapp
openclaw channels status
```

Symptome : compte lie avec des deconnexions repetees ou des tentatives de reconnexion.

Correction :

```bash
openclaw doctor
openclaw logs --follow
```

Si necessaire, reliez avec `channels login`.

Les envois sortants echouent immediatement lorsqu'aucun ecouteur actif de la gateway n'existe pour le compte cible.

Assurez-vous que la gateway est en cours d'execution et que le compte est lie.

Verifiez dans cet ordre :

- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- entrees de la liste d'autorisation `groups`
- verification de mention (`requireMention` + patrons de mention)
- cles en double dans `openclaw.json` (JSON5) : les entrees ulterieures ecrasent les precedentes, conservez donc un seul `groupPolicy` par portee

L'execution de la gateway WhatsApp devrait utiliser Node. Bun est signale comme incompatible pour une operation stable de la gateway WhatsApp/Telegram.

Pointeurs de reference de configuration

Reference principale :

• Reference de configuration - WhatsApp

Champs WhatsApp a fort signal :

• acces : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• livraison : textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• multi-comptes : accounts.<id>.enabled, accounts.<id>.authDir, surcharges au niveau du compte
• operations : configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• comportement de session : session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Voir aussi

• Appairage
• Routage des canaux
• Routage multi-agents
• Depannage