WhatsApp

Statut : prêt pour la production via WhatsApp Web (Baileys). Le Gateway gère la ou les sessions associées ; il n’existe pas de canal WhatsApp Twilio distinct.

Installation

openclaw onboard et openclaw channels add --channel whatsapp proposent d’installer le plugin lors de sa première sélection ; openclaw channels login --channel whatsapp propose le même processus d’installation si le plugin est absent. Les extractions de développement utilisent le chemin local du plugin ; les installations stables/bêta installent d’abord @openclaw/whatsapp depuis ClawHub, avec repli sur npm. Le runtime WhatsApp est distribué en dehors du paquet npm principal d’OpenClaw ; ses dépendances d’exécution restent donc avec le plugin externe. Installation manuelle :

openclaw plugins install clawhub:@openclaw/whatsapp

Utilisez le paquet npm seul (@openclaw/whatsapp) uniquement pour le repli vers le registre ; épinglez une version exacte uniquement pour une installation reproductible.

Configuration rapide

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Modèles de déploiement

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

Modèle d’exécution

• Le Gateway gère le socket WhatsApp et la boucle de reconnexion.
• Un processus de surveillance suit indépendamment deux signaux : l’activité brute du transport WhatsApp Web et l’activité des messages applicatifs. Une session silencieuse mais connectée n’est pas redémarrée simplement parce qu’aucun message n’est arrivé récemment ; une reconnexion n’est forcée que lorsque les trames de transport cessent d’arriver pendant une fenêtre interne fixe (non configurable par l’utilisateur) ou lorsque les messages applicatifs restent silencieux au-delà de 4 fois le délai normal des messages. Juste après la reconnexion d’une session récemment active, cette première fenêtre utilise le délai normal des messages, plus court, au lieu de la fenêtre multipliée par 4. OpenClaw peut répondre automatiquement aux messages hors ligne que Baileys transmet au début de cette reconnexion, dans la limite de la durée de vie de la déduplication des identifiants de messages ; le démarrage initial conserve la courte protection contre l’historique obsolète.
• Les délais du socket Baileys sont définis explicitement sous web.whatsapp.* : keepAliveIntervalMs (intervalle des signaux ping de l’application), connectTimeoutMs (délai d’expiration de la négociation initiale), defaultQueryTimeoutMs (attentes des requêtes Baileys, ainsi que délais d’expiration d’OpenClaw pour les envois sortants, la présence et les accusés de lecture entrants).
• Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible ; sinon, ils échouent immédiatement.
• Les envois aux groupes joignent des métadonnées natives de mention pour les jetons @+<digits> et @<digits> (dans le texte et les légendes des médias) lorsque le jeton correspond aux métadonnées actuelles d’un participant, y compris dans les groupes basés sur un LID.
• Les discussions de statut et de diffusion (@status, @broadcast) sont ignorées.
• Les discussions directes utilisent les règles de session des messages privés (session.dmScope ; la valeur par défaut main regroupe les messages privés dans la session principale de l’agent). Les sessions de groupe sont isolées par JID (agent:<agentId>:whatsapp:group:<jid>).
• Les canaux et newsletters WhatsApp peuvent être des cibles sortantes explicites par l’intermédiaire de leur JID @newsletter natif, en utilisant les métadonnées de session de canal (agent:<agentId>:whatsapp:channel:<jid>) plutôt que la sémantique des messages privés.
• Le transport WhatsApp Web respecte les variables d’environnement de proxy standard sur l’hôte du Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, ainsi que leurs variantes en minuscules). Préférez la configuration du proxy au niveau de l’hôte aux paramètres propres à chaque canal.
• Lorsque messages.removeAckAfterReply est activé, OpenClaw supprime la réaction d’accusé de réception dès qu’une réponse visible est remise.

Appeler le demandeur actuel avec MeowCaller (expérimental)

Le plugin peut exposer whatsapp_call lors des tours d’agent provenant de WhatsApp. Il utilise MeowCaller pour passer un appel vocal WhatsApp au demandeur actuellement autorisé et lire un message TTS d’OpenClaw après sa réponse. L’outil ne possède aucun paramètre de numéro de destination ; une invite ne peut donc pas rediriger l’appel. Désactivé par défaut.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Limites : appels audio sortants individuels uniquement, aucun numéro de destination arbitraire, aucune authentification partagée avec la connexion de discussion, aucun appel vers soi-même en mode avec numéro personnel ou conversation avec soi-même, audio synthétisé limité à 60 secondes, aucun accusé d’audibilité côté combiné au-delà de l’achèvement de la réponse, de la lecture et du raccrochage par MeowCaller, et OpenClaw arrête le processus compagnon après une fenêtre limitée de 115 à 175 secondes (couvrant les phases de connexion, de réponse, de lecture et d’arrêt de MeowCaller).

Invites d’approbation

WhatsApp peut afficher les invites d’approbation d’exécution et de plugin sous forme de réactions 👍/👎, contrôlées par la configuration générale de transfert des approbations :

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec et approvals.plugin sont indépendants ; l’activation de WhatsApp en tant que canal associe uniquement le transport et n’envoie rien, sauf si la famille d’approbations correspondante est activée et routée vers ce canal. Le mode session transmet les approbations natives par emoji uniquement pour les approbations provenant de WhatsApp. Le mode cible utilise le pipeline de transfert partagé pour les cibles explicites et ne crée pas de diffusion distincte vers les messages privés des approbateurs.

Les réactions d’approbation WhatsApp nécessitent des approbateurs explicitement définis dans allowFrom (ou "*"). defaultTo définit les cibles ordinaires par défaut des messages, et non une liste d’approbateurs. Les commandes manuelles /approve suivent toujours le processus normal d’autorisation des expéditeurs WhatsApp avant la résolution de l’approbation.

Hooks de plugin et confidentialité

Les messages WhatsApp entrants peuvent contenir du contenu personnel, des numéros de téléphone, des identifiants de groupe, des noms d’expéditeurs et des champs de corrélation de session. WhatsApp ne diffuse pas aux plugins les charges utiles entrantes du hook message_received, sauf si vous les activez explicitement :

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Limitez l’activation à un seul compte sous channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Activez cette option uniquement pour les plugins auxquels vous faites confiance pour traiter le contenu et les identifiants WhatsApp entrants.

Contrôle d’accès et activation

Liaisons ACP configurées

WhatsApp prend en charge les liaisons ACP persistantes via le niveau supérieur bindings[] :

{  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" },      },    },  ],}

Les conversations directes correspondent aux numéros E.164 ; les groupes correspondent aux JID de groupe WhatsApp. Les listes d’autorisations de groupes, la politique relative aux expéditeurs et les contrôles de mention ou d’activation sont appliqués avant qu’OpenClaw ne vérifie l’existence de la session ACP liée. Une liaison correspondante contrôle le routage — les groupes de diffusion ne distribuent pas cette interaction aux sessions WhatsApp ordinaires.

Comportement du numéro personnel et de la conversation avec soi-même

Lorsque le numéro personnel associé figure également dans allowFrom, les protections de conversation avec soi-même s’activent : les accusés de lecture sont ignorés pour ces interactions, le déclenchement automatique par JID de mention qui vous notifierait vous-même est désactivé et les réponses utilisent par défaut [{identity.name}] (ou [openclaw]) lorsque messages.responsePrefix n’est pas défini.

Normalisation des messages et contexte

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

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

Livraison, découpage et médias

Citation des réponses

channels.whatsapp.replyToMode contrôle la citation native des réponses (les réponses sortantes citent visiblement le message entrant) :

Remplacement par compte : channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Niveau de réaction

channels.whatsapp.reactionLevel contrôle l’étendue de l’utilisation des réactions emoji par l’agent :

Remplacement par compte : channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

Réactions d’accusé de réception

channels.whatsapp.ackReaction envoie une réaction immédiate à la réception d’un message entrant, sous le contrôle de reactionLevel (supprimée lorsque "off") :

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

Remarques : envoyée immédiatement après l’acceptation du message entrant (avant la réponse) ; si ackReaction est présent sans emoji, WhatsApp utilise l’emoji d’identité de l’agent destinataire, avec « 👀 » comme valeur de secours (omettez ackReaction ou définissez emoji: "" pour désactiver l’accusé de réception) ; les échecs sont consignés dans les journaux, mais ne bloquent pas la livraison de la réponse ; le mode de groupe mentions ne réagit qu’aux interactions déclenchées par une mention, tandis que l’activation de groupe always contourne cette vérification ; WhatsApp utilise uniquement channels.whatsapp.ackReaction (l’ancien messages.ackReaction ne s’applique pas ici).

Réactions d’état du cycle de vie

Définissez messages.statusReactions.enabled: true pour permettre à WhatsApp de remplacer la réaction d’accusé de réception au cours d’une interaction, au lieu de conserver un emoji de réception statique, en parcourant des états tels que mise en file d’attente, réflexion, activité des outils, Compaction, terminé et erreur :

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Remarques : channels.whatsapp.ackReaction contrôle toujours l’admissibilité pour les messages privés et les groupes ; l’état de mise en file d’attente utilise le même emoji effectif que les réactions ordinaires d’accusé de réception ; WhatsApp dispose d’un seul emplacement de réaction du bot par message, les mises à jour du cycle de vie remplacent donc la réaction actuelle sur place ; messages.removeAckAfterReply: true efface la réaction d’état finale après la durée de maintien configurée pour la réussite ou l’erreur ; les catégories d’emoji d’outils comprennent tool, coding, web, deploy, build et concierge.

Comptes multiples et identifiants

Outils, actions et écritures de configuration

• La prise en charge des outils de l’agent inclut l’action de réaction WhatsApp (react).
• Contrôles des actions : channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (les actions existantes utilisent par défaut true), channels.whatsapp.actions.calls (valeur par défaut : false, voir MeowCaller ci-dessus).
• Les écritures de configuration initiées par le canal sont activées par défaut ; désactivez-les via channels.whatsapp.configWrites: false.

Dépannage

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Invites système

WhatsApp prend en charge les invites système de type Telegram pour les groupes et les discussions directes via les tables groups et direct.

Résolution pour les messages de groupe : la table groups effective est d’abord déterminée — si le compte définit sa propre clé groups, elle remplace entièrement la table racine groups (sans fusion profonde). La recherche de l’invite s’effectue ensuite sur cette unique table résultante :

1. Invite propre au groupe (groups["<groupId>"].systemPrompt) : utilisée lorsque l’entrée du groupe existe et que sa clé systemPrompt est définie. Une chaîne vide ("") désactive le caractère générique et n’applique aucune invite.
2. Invite générique des groupes (groups["*"].systemPrompt) : utilisée lorsque l’entrée du groupe concerné est absente ou existe sans clé systemPrompt.

La résolution des messages directs suit le même modèle pour la table direct et direct["*"].

Différence avec Telegram : Telegram ignore la valeur racine groups pour chaque compte d’une configuration multicomptes (même pour les comptes qui ne possèdent aucun groups) afin d’empêcher un bot de recevoir des messages provenant de groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection — les valeurs racines groups/direct sont héritées par tout compte sans remplacement propre, quel que soit le nombre de comptes. Dans une configuration WhatsApp multicomptes, définissez explicitement la table complète sous chaque compte si vous souhaitez des invites propres à chaque compte.

Comportements importants :

• channels.whatsapp.groups est à la fois une table de configuration propre à chaque groupe et la liste d’autorisation des groupes au niveau de la discussion. À la portée racine ou à celle du compte, groups["*"] signifie « tous les groupes sont autorisés » pour cette portée.
• N’ajoutez un caractère générique systemPrompt que si vous souhaitez déjà autoriser tous les groupes pour cette portée. Pour limiter l’admissibilité à un ensemble fixe d’identifiants de groupe, répétez l’invite dans chaque entrée explicitement autorisée au lieu d’utiliser groups["*"].
• L’admission des groupes et l’autorisation des expéditeurs sont deux vérifications distinctes. groups["*"] élargit l’ensemble des groupes qui atteignent le traitement des groupes ; il n’autorise pas tous les expéditeurs de ces groupes — cela reste contrôlé par groupPolicy/groupAllowFrom.
• channels.whatsapp.direct n’a aucun effet secondaire équivalent pour les messages directs : direct["*"] fournit uniquement une configuration par défaut après qu’un message direct a déjà été admis par dmPolicy ainsi que par allowFrom ou les règles du magasin de liaisons.

Exemple :

{  channels: {    whatsapp: {      groups: {        // À utiliser uniquement si tous les groupes doivent être autorisés à la portée racine.        // S’applique à tous les comptes qui ne définissent pas leur propre table de groupes.        "*": { systemPrompt: "Invite par défaut pour tous les groupes." },      },      direct: {        // S’applique à tous les comptes qui ne définissent pas leur propre table de discussions directes.        "*": { systemPrompt: "Invite par défaut pour toutes les discussions directes." },      },      accounts: {        work: {          groups: {            // Ce compte définit ses propres groupes ; les groupes racines sont donc entièrement            // remplacés. Pour conserver un caractère générique, définissez aussi explicitement "*" ici.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Se concentrer sur la gestion de projet.",            },            // À utiliser uniquement si tous les groupes doivent être autorisés pour ce compte.            "*": { systemPrompt: "Invite par défaut pour les groupes professionnels." },          },          direct: {            // Ce compte définit sa propre table de discussions directes ; les entrées directes racines sont donc            // entièrement remplacées. Pour conserver un caractère générique, définissez aussi explicitement "*" ici.            "+15551234567": { systemPrompt: "Invite pour une discussion professionnelle directe spécifique." },            "*": { systemPrompt: "Invite par défaut pour les discussions professionnelles directes." },          },        },      },    },  },}

Renvois vers la référence de configuration

Référence principale : Référence de configuration - WhatsApp

Pages connexes

• Liaison
• Groupes
• Sécurité
• Routage des canaux
• Routage multi-agent
• Dépannage