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 la première fois que vous le sélectionnez ; openclaw channels login --channel whatsapp offre le même processus d’installation si le Plugin est absent. Les versions de développement utilisent le chemin local du Plugin ; les installations stables/bêta installent d’abord @openclaw/whatsapp depuis ClawHub, puis se rabattent sur npm. L’environnement d’exécution WhatsApp est distribué en dehors du paquet npm principal d’OpenClaw ; ses dépendances d’exécution restent donc associées au Plugin externe. Installation manuelle :

openclaw plugins install clawhub:@openclaw/whatsapp

Utilisez le paquet npm seul (@openclaw/whatsapp) uniquement comme solution de repli vers le registre ; épinglez une version exacte uniquement pour garantir 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 période interne fixe, non configurable par l’utilisateur, ou lorsque les messages applicatifs restent silencieux pendant plus de quatre fois le délai d’expiration normal des messages. Juste après la reconnexion d’une session récemment active, cette première période utilise le délai d’expiration normal, plus court, au lieu de la période quatre fois plus longue. 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 entrants ; le démarrage initial conserve la courte protection contre l’historique obsolète.
• Les temporisations du socket Baileys sont explicitement définies sous web.whatsapp.* : keepAliveIntervalMs (intervalle des requêtes ping applicatives), connectTimeoutMs (délai d’expiration de la négociation d’ouverture), defaultQueryTimeoutMs (attente des requêtes Baileys, ainsi que délais d’expiration d’OpenClaw pour l’envoi sortant, la présence et les accusés de lecture entrants).
• Les envois sortants exigent un écouteur WhatsApp actif pour le compte cible ; sinon, ils échouent immédiatement.
• Les envois de groupe joignent des métadonnées de mention natives pour les jetons @+<digits> et @<digits> dans le texte et les légendes de médias lorsque le jeton correspond aux métadonnées actuelles d’un participant, y compris dans les groupes reposant sur des 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 lettres d’information WhatsApp peuvent être des cibles sortantes explicites au moyen de leur JID @newsletter natif, avec les métadonnées de session du 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 et leurs variantes en minuscules). Préférez une configuration de proxy au niveau de l’hôte aux paramètres propres à chaque canal.
• Lorsque messages.removeAckAfterReply est activé, OpenClaw efface 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 qu’il a répondu. L’outil ne possède aucun paramètre de numéro de destination ; une invite ne peut donc pas rediriger l’appel. Cette fonctionnalité est désactivée 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 : uniquement des appels audio sortants individuels, aucun numéro de destination arbitraire, aucune authentification partagée avec la connexion de discussion, aucun appel vers soi-même depuis le mode avec numéro personnel ou discussion avec soi-même, audio synthétisé limité à 60 secondes, aucun accusé d’audibilité côté combiné au-delà de la confirmation par MeowCaller de la réponse, de la lecture et du raccrochage, et OpenClaw arrête le processus compagnon après une période 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 de transfert des approbations de premier niveau :

{  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 comme 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 fournit des approbations natives par émoji 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 de messages privés aux approbateurs.

Les réactions d’approbation WhatsApp exigent des approbateurs explicitement indiqués 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 de l’expéditeur WhatsApp avant la résolution de l’approbation.

Hooks de Plugin et confidentialité

Les messages WhatsApp entrants peuvent contenir des informations personnelles, 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 les charges utiles du hook entrant message_received aux Plugins, sauf si vous l’activez explicitement :

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

Limitez cette activation à un seul compte sous channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Activez-la 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 au moyen de bindings[] au niveau supérieur :

{  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 discussions directes correspondent aux numéros au format E.164 ; les groupes correspondent aux JID de groupe WhatsApp. Les listes d’autorisations de groupes, la politique relative aux expéditeurs et les conditions d’activation par mention ou commande sont appliquées avant qu’OpenClaw ne vérifie l’existence de la session ACP liée. Une liaison correspondante prend en charge le routage — les groupes de diffusion ne distribuent pas ce tour aux sessions WhatsApp ordinaires.

Comportement du numéro personnel et des discussions avec soi-même

Lorsque le numéro personnel lié figure également dans allowFrom, les mesures de protection des discussions avec soi-même sont activées : les accusés de lecture sont ignorés pour ces tours, le déclenchement automatique par JID de mention susceptible de vous notifier 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 réserve de reactionLevel (supprimée lorsque la valeur est "off") :

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

Remarques : la réaction est 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 vers lequel le message est acheminé, avec « 👀 » comme valeur de repli (omettez ackReaction ou définissez emoji: "" pour n’envoyer aucun accusé) ; 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 tours déclenchés par une mention, tandis que l’activation de groupe always contourne cette vérification ; WhatsApp utilise uniquement channels.whatsapp.ackReaction (l’ancienne option 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’un tour au lieu de laisser un emoji de réception statique, en parcourant des états tels que la mise en file d’attente, la réflexion, l’activité des outils, la Compaction, la fin et l’erreur :

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

Remarques : channels.whatsapp.ackReaction contrôle toujours l’éligibilité 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 d’accusé de réception ordinaires ; WhatsApp dispose d’un seul emplacement de réaction du bot par message, de sorte que les mises à jour du cycle de vie remplacent directement la réaction actuelle ; messages.removeAckAfterReply: true efface la réaction d’état finale après la durée de maintien configurée pour la fin ou l’erreur ; les catégories d’emoji des outils comprennent tool, coding, web, deploy, build et concierge.

Comptes multiples et identifiants

Outils, actions et écritures de configuration

• Les outils de l’agent prennent en charge l’action de réaction WhatsApp (react).
• Contrôles des actions : channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (les actions existantes valent true par défaut), 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 avec 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 au moyen des 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 groups racine, sans fusion récursive. La recherche de l’invite s’effectue ensuite dans 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 ("") neutralise le joker et n’applique aucune invite.
2. Invite générique de groupe (groups["*"].systemPrompt) : utilisée lorsque l’entrée propre au groupe est absente ou existe sans clé systemPrompt.

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

Différence par rapport à Telegram : Telegram neutralise la table groups racine pour chaque compte d’une configuration multicomptes, même pour les comptes dépourvus de leur propre table groups, afin d’empêcher un bot de recevoir les messages de groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection : les tables groups/direct racines sont héritées par tout compte dépourvu de son propre remplacement, 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 par groupe et la liste d’autorisation des groupes au niveau de la discussion. À la portée racine comme à celle du compte, groups["*"] signifie que tous les groupes sont autorisés pour cette portée.
• N’ajoutez un systemPrompt générique que si vous souhaitez déjà que cette portée autorise tous les groupes. Pour limiter l’éligibilité à un ensemble déterminé 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 — cette autorisation reste contrôlée 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é autorisé par dmPolicy, conjointement avec allowFrom ou les règles du registre d’association.

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 groups.        "*": { systemPrompt: "Invite par défaut pour tous les groupes." },      },      direct: {        // S’applique à tous les comptes qui ne définissent pas leur propre table direct.        "*": { 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 joker, 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 dans ce compte.            "*": { systemPrompt: "Invite par défaut pour les groupes professionnels." },          },          direct: {            // Ce compte définit sa propre table direct ; les entrées direct racines sont donc            // entièrement remplacées. Pour conserver un joker, définissez aussi "*" explicitement ici.            "+15551234567": { systemPrompt: "Invite pour une discussion directe professionnelle précise." },            "*": { systemPrompt: "Invite par défaut pour les discussions directes professionnelles." },          },        },      },    },  },}

Repères de référence de la configuration

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

Pages connexes

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