Guide complet de l'integration WhatsApp avec OpenClaw

Apercu

L'integration WhatsApp vous permet de discuter avec votre assistant IA OpenClaw directement via WhatsApp. OpenClaw utilise WhatsApp Web via Baileys — la passerelle possede la ou les sessions et gere toute la communication. Vous lierez votre compte WhatsApp de maniere similaire a la facon dont vous lieriez WhatsApp Web sur un navigateur.

Prerequis

Avant de commencer, assurez-vous d'avoir :

• OpenClaw installe et la passerelle en cours d'execution
• Un compte WhatsApp avec un vrai numero de telephone mobile (les numeros VoIP et virtuels sont generalement bloques par WhatsApp)
• Le runtime Node.js (Bun n'est pas recommande — WhatsApp/Baileys est instable sous Bun)

Obtenir un numero de telephone

WhatsApp exige un vrai numero de telephone mobile pour la verification. Deux modes sont pris en charge :

Numero dedie (Recommande)

Utilisez un numero de telephone distinct pour OpenClaw. Cela offre la meilleure experience utilisateur avec un routage propre et sans particularites liees au self-chat. La configuration ideale est un ancien telephone Android + eSIM — laissez-le branche au Wi-Fi et au courant, puis liez-le via QR.

Conseils pour obtenir un numero :

• eSIM locale de l'operateur mobile de votre pays (le plus fiable)
• Carte SIM prepayee — peu couteuse, il suffit de recevoir un SMS de verification
• A eviter : TextNow, Google Voice, la plupart des services "SMS gratuits" — WhatsApp les bloque activement

Le numero n'a besoin de recevoir qu'un seul SMS de verification. Apres cela, les sessions WhatsApp Web persistent via creds.json.

Astuce : Vous pouvez utiliser WhatsApp Business sur le meme appareil avec un numero different. C'est ideal pour garder votre WhatsApp personnel separe — installez WhatsApp Business et enregistrez-y le numero OpenClaw.

Numero personnel (Solution de repli)

Solution rapide : executez OpenClaw sur votre propre numero. Envoyez-vous des messages a vous-meme (la fonctionnalite "M'envoyer un message" de WhatsApp) pour tester sans deranger vos contacts. Vous devez activer le mode self-chat dans ce cas.

Etape 1 : Configurer WhatsApp

Editez votre ~/.openclaw/openclaw.json.

Configuration avec numero dedie

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

Remplacez +15551234567 par le(s) numero(s) de telephone que vous souhaitez autoriser a discuter avec l'assistant (format E.164).

Configuration avec numero personnel (Mode Self-Chat)

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

En mode self-chat, entrez le numero de telephone depuis lequel vous envoyez les messages (le proprietaire/expediteur), et non le numero de l'assistant. Les reponses en self-chat utilisent par defaut [{identity.name}] comme prefixe (ou [openclaw] si non defini). Vous pouvez personnaliser cela via messages.responsePrefix ou le definir a "" pour le supprimer.

Etape 2 : Lier votre compte WhatsApp

Executez la commande de connexion :

openclaw channels login

Cela affichera un QR code dans votre terminal. Sur votre telephone :

1. Ouvrez WhatsApp
2. Allez dans Parametres > Appareils lies
3. Appuyez sur Lier un appareil
4. Scannez le QR code affiche dans votre terminal

Pour les configurations multi-comptes, specifiez le compte :

openclaw channels login --account <accountId>

Le compte par defaut (lorsque --account est omis) est default s'il est present, sinon le premier identifiant de compte configure (tri alphabetique).

Etape 3 : Demarrer la passerelle

Demarrez la passerelle OpenClaw pour commencer a recevoir des messages. La passerelle possede le socket Baileys et la boucle de reception — le CLI et l'application macOS communiquent avec la passerelle, sans utilisation directe de Baileys.

Important : Un listener actif est requis pour les envois sortants ; sinon, les envois echoueront immediatement.

Controle d'acces aux messages directs

OpenClaw propose trois modes de politique de messages directs via channels.whatsapp.dmPolicy :

Mode Pairing (Par defaut)

Les expediteurs inconnus recoivent un code de couplage a duree limitee. Leur message n'est pas traite tant qu'il n'est pas approuve.

# Approuver une demande de couplage
openclaw pairing approve whatsapp <code>

# Lister les demandes de couplage en attente
openclaw pairing list whatsapp

Les codes de couplage expirent apres 1 heure, et les demandes en attente sont limitees a 3 par canal.

Mode Allowlist

Seuls les numeros de telephone listes dans channels.whatsapp.allowFrom peuvent initier des conversations.

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

Mode Open

Necessite que channels.whatsapp.allowFrom inclue "*".

Note : Votre numero WhatsApp lie est implicitement approuve — les messages envoyes a soi-meme ignorent les verifications dmPolicy et allowFrom.

Accuses de reception

Par defaut, la passerelle marque les messages WhatsApp entrants comme lus (coches bleues) une fois acceptes.

Desactiver globalement :

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

Desactiver par compte :

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

Le mode self-chat ignore toujours les accuses de reception.

Support des discussions de groupe

Les groupes sont associes a des sessions dediees. Configurez le comportement des groupes avec :

• Politique de groupe : channels.whatsapp.groupPolicy — open, disabled ou allowlist (par defaut : allowlist)
• Modes d'activation :
  • mention (par defaut) : necessite une @mention ou une correspondance regex
  • always : declenche toujours une reponse

Basculez l'activation avec une commande reservee au proprietaire (doit etre un message independant) :

/activation mention
/activation always

Le proprietaire est determine par channels.whatsapp.allowFrom (ou votre numero E.164 si non defini).

Contexte d'historique de groupe

Les messages non traites recents (50 par defaut) sont automatiquement injectes comme contexte :

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

Chaque message inclut un suffixe d'expediteur : [from: Name (+E164)].

Les metadonnees du groupe (sujet + participants) sont mises en cache pendant 5 minutes.

Reactions d'accusation de reception

WhatsApp peut automatiquement envoyer des reactions emoji aux messages entrants des leur reception, fournissant un retour instantane avant que le bot ne genere sa reponse.

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

Options :

• emoji : Emoji utilise pour reagir (par exemple, "👀", "✅"). Vide ou omis desactive la fonctionnalite.
• direct (par defaut : true) : Envoyer des reactions dans les conversations directes.
• group (par defaut : "mentions") :
  • "always" : Reagir a tous les messages de groupe
  • "mentions" : Reagir uniquement lorsque le bot est @mentionne
  • "never" : Ne jamais reagir dans les groupes

Surcharge par compte :

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

Les reactions sont envoyees immediatement des la reception, avant les indicateurs de saisie ou les reponses du bot. Les echecs sont journalises mais n'empechent pas le bot de repondre.

Gestion des messages

Messages entrants

• Les messages arrivent via les evenements messages.upsert de Baileys
• Les chats de statut/diffusion sont ignores
• Les conversations directes utilisent le format E.164 ; les groupes utilisent le JID de groupe
• Le contexte des reponses citees est toujours ajoute pour fournir le contexte de la conversation
• Les messages contenant uniquement des medias utilisent des espaces reserves : <media:image|video|audio|document|sticker>

Messages sortants

• Le texte est decoupe en morceaux de 4 000 caracteres par defaut (configurable via channels.whatsapp.textChunkLimit)
• Decoupage optionnel par saut de ligne : definissez channels.whatsapp.chunkMode="newline" pour decouper aux limites de paragraphe avant le decoupage par longueur
• Types de medias pris en charge : image, video, audio, document
• L'audio est envoye sous forme de notes vocales (PTT). Meilleurs resultats avec le format OGG/Opus
• La legende n'est presente que sur le premier element multimedia
• GIFs animes : WhatsApp attend un MP4 avec gifPlayback: true pour la lecture en boucle integree

Limites multimedia

• Limite de sauvegarde des medias entrants : 50 Mo (configurable via channels.whatsapp.mediaMaxMb)
• Limite des medias sortants : 5 Mo par element (configurable via agents.defaults.mediaMaxMb)
• Les images sont automatiquement optimisees en JPEG lorsqu'elles sont sous la limite (redimensionnement + ajustement de qualite)
• Les medias surdimensionnes generent une erreur ; la reponse multimedia revient a un avertissement textuel

Identifiants et stockage

• Les identifiants sont stockes dans : ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Sauvegarde automatique dans creds.json.bak (restauration en cas de corruption)
• Deconnexion : openclaw channels logout (ou --account <id>) supprime l'etat d'authentification WhatsApp mais conserve le fichier oauth.json partage

Support multi-comptes

Plusieurs comptes WhatsApp peuvent fonctionner dans un seul processus de passerelle. Utilisez des identifiants de compte dans la configuration :

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* parametres par compte */ },
        work: { /* parametres par compte */ },
      },
    },
  },
}

Les parametres par compte prennent en charge les surcharges pour sendReadReceipts, ackReaction, mediaMaxMb, historyLimit, et plus encore.

Pourquoi pas Twilio / WhatsApp Business API ?

Les premieres versions d'OpenClaw supportaient l'integration WhatsApp Business de Twilio, mais elle a ete retiree car :

• Les numeros WhatsApp Business sont mal adaptes a un assistant personnel
• Meta impose une fenetre de reponse de 24 heures — si vous n'avez pas repondu dans les 24 dernieres heures, le numero professionnel ne peut pas initier de nouveaux messages
• Une utilisation intensive ou "bavarde" declenche un blocage agressif, car les comptes professionnels ne sont pas concus pour une utilisation de type assistant personnel
• Resultat : livraison peu fiable et blocages frequents

Reference rapide de configuration

| Cle de configuration | Description | |---|---| | channels.whatsapp.dmPolicy | Politique de messages directs : pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Activer pour la configuration avec numero personnel | | channels.whatsapp.allowFrom | Liste d'autorisation DM (numeros de telephone E.164) | | channels.whatsapp.sendReadReceipts | Accuses de reception automatiques (par defaut : true) | | channels.whatsapp.ackReaction | Reaction automatique a la reception du message | | channels.whatsapp.groupPolicy | Politique de groupe : open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Taille des morceaux de texte sortants (par defaut : 4000) | | channels.whatsapp.mediaMaxMb | Limite des medias entrants (par defaut : 50 Mo) | | channels.whatsapp.configWrites | Autoriser les ecritures de configuration via la commande /config | | agents.defaults.mediaMaxMb | Limite des medias sortants (par defaut : 5 Mo) |

Depannage

Non lie / Connexion QR requise

Symptome : channels status affiche linked: false ou avertit "Not linked".

Solution : Executez openclaw channels login sur l'hote de la passerelle et scannez le QR code (WhatsApp > Parametres > Appareils lies).

Lie mais deconnecte / Boucle de reconnexion

Symptome : channels status affiche running, disconnected ou avertit "Linked but disconnected".

Solution : Executez openclaw doctor ou redemarrez la passerelle. Si le probleme persiste, reliez via openclaw channels login et inspectez openclaw logs --follow.

Problemes avec le runtime Bun

Bun n'est pas recommande. WhatsApp (Baileys) et Telegram sont instables sous Bun. Executez la passerelle avec Node.js.

Comportement de reconnexion

La passerelle utilise une politique de backoff (web.reconnect) avec des parametres configurables : initialMs, maxMs, factor, jitter et maxAttempts. Si le nombre maximal de tentatives est atteint, la surveillance web s'arrete (mode degrade). Un socket deconnecte s'arrete et necessite une nouvelle liaison.

Prochaines etapes

• Guide d'integration Telegram
• Guide d'integration Discord
• Documentation officielle WhatsApp