WhatsApp

Statut : prêt pour la production via WhatsApp Web (Baileys). Gateway gère les sessions liées.

Installation (à la demande)

• L’onboarding (openclaw onboard) et openclaw channels add --channel whatsapp proposent d’installer le Plugin WhatsApp la première fois que vous le sélectionnez.
• openclaw channels login --channel whatsapp propose également le flux d’installation lorsque le Plugin n’est pas encore présent.
• Canal de développement + extraction git : utilise par défaut le chemin local du Plugin.
• Stable/Bêta : installe d’abord le Plugin officiel @openclaw/whatsapp depuis ClawHub, avec npm comme solution de repli.
• Le runtime WhatsApp est distribué en dehors du paquet npm OpenClaw principal afin que les dépendances de runtime propres à WhatsApp restent avec le Plugin externe.

L’installation manuelle reste disponible :

openclaw plugins install clawhub:@openclaw/whatsapp

Utilisez le paquet npm brut (@openclaw/whatsapp) uniquement lorsque vous avez besoin de la solution de repli du registre. Épinglez une version exacte uniquement lorsque vous avez besoin d’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>

Appeler le demandeur actuel avec MeowCaller (expérimental)

Le Plugin WhatsApp peut exposer whatsapp_call dans les tours d’agent provenant de WhatsApp. L’outil utilise MeowCaller pour passer un appel vocal WhatsApp au demandeur autorisé actuel et lit un message TTS OpenClaw après qu’il a répondu. L’outil n’accepte pas de numéro de destination, un prompt ne peut donc pas rediriger l’appel vers un tiers. Cette capacité expérimentale 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 actuelles :

• appels audio sortants individuels uniquement
• aucun numéro de destination arbitraire
• aucune authentification partagée avec la connexion de discussion
• aucun auto-appel en mode numéro personnel/self-chat
• l’audio synthétisé est limité à 60 secondes
• aucun accusé d’audibilité côté combiné au-delà de la fin réponse/lecture/raccrochage de MeowCaller
• OpenClaw arrête le processus compagnon après une fenêtre bornée de 115 à 175 secondes, incluant les phases de connexion, réponse, lecture et arrêt de MeowCaller

Modèles de déploiement

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

Modèle de runtime

• Gateway gère le socket WhatsApp et la boucle de reconnexion.
• Le watchdog de reconnexion utilise l’activité du transport WhatsApp Web, pas seulement le volume de messages d’application entrants, de sorte qu’une session d’appareil lié silencieuse n’est pas redémarrée uniquement parce que personne n’a envoyé de message récemment. Un plafond plus long de silence applicatif force tout de même une reconnexion si des trames de transport continuent d’arriver mais qu’aucun message d’application n’est traité pendant la fenêtre du watchdog ; après une reconnexion transitoire pour une session récemment active, ce contrôle de silence applicatif utilise le timeout normal des messages pour la première fenêtre de récupération.
• Les temporisations du socket Baileys sont explicites sous web.whatsapp.* : keepAliveIntervalMs contrôle les pings d’application WhatsApp Web, connectTimeoutMs contrôle le timeout de la poignée de main d’ouverture, et defaultQueryTimeoutMs contrôle les attentes de requête Baileys ainsi que les limites locales OpenClaw pour l’envoi/la présence sortants et les opérations d’accusé de lecture entrants.
• Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible.
• Les envois de groupe attachent 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 des participants WhatsApp, y compris les groupes adossés à LID.
• Les discussions de statut et de diffusion sont ignorées (@status, @broadcast).
• Le watchdog de reconnexion suit l’activité du transport WhatsApp Web, pas seulement le volume de messages d’application entrants : les sessions d’appareil lié silencieuses restent actives tant que les trames de transport continuent, mais un blocage du transport force une reconnexion bien avant le chemin ultérieur de déconnexion distante.
• Les discussions directes utilisent les règles de session DM (session.dmScope ; la valeur par défaut main regroupe les DM dans la session principale de l’agent).
• Les sessions de groupe sont isolées (agent:<agentId>:whatsapp:group:<jid>).
• Les Canaux/Newsletters WhatsApp peuvent être des cibles sortantes explicites avec leur JID natif @newsletter. Les envois de newsletter sortants utilisent les métadonnées de session de canal (agent:<agentId>:whatsapp:channel:<jid>) plutôt que la sémantique des sessions DM.
• Le transport WhatsApp Web respecte les variables d’environnement de proxy standard sur l’hôte du Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes en minuscules). Préférez la configuration de proxy au niveau de l’hôte aux paramètres de proxy WhatsApp propres au canal.
• Lorsque messages.removeAckAfterReply est activé, OpenClaw efface la réaction d’accusé WhatsApp après la remise d’une réponse visible.

Prompts d’approbation

WhatsApp peut afficher les prompts d’approbation d’exec et de Plugin avec des réactions 👍 / 👎. La livraison est contrôlée par la configuration de transfert d’approbation 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. Activer WhatsApp comme canal ne fait que lier le transport ; cela n’envoie pas de prompts d’approbation sauf si la famille d’approbation correspondante est activée et route vers WhatsApp. Le mode session livre les approbations emoji natives uniquement pour les approbations qui proviennent de WhatsApp. Le mode cible utilise le pipeline de transfert partagé pour les cibles WhatsApp explicites et ne crée pas de fanout de DM d’approbateur séparé.

Les réactions d’approbation WhatsApp nécessitent des approbateurs WhatsApp explicites depuis allowFrom ou "*". defaultTo contrôle les cibles de messages ordinaires par défaut ; ce n’est pas un approbateur d’approbation. Les commandes /approve manuelles passent toujours par le chemin d’autorisation normal de l’expéditeur WhatsApp avant la résolution de l’approbation.

Hooks de Plugin et confidentialité

Les messages entrants WhatsApp peuvent contenir le contenu personnel des messages, des numéros de téléphone, des identifiants de groupe, des noms d’expéditeur et des champs de corrélation de session. Pour cette raison, WhatsApp ne diffuse pas les payloads de hook entrants message_received aux plugins, sauf si vous l’activez explicitement :

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

Vous pouvez limiter l’activation à un seul compte :

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

N’activez cette option que pour les plugins auxquels vous faites confiance pour recevoir le contenu et les identifiants des messages entrants WhatsApp.

Contrôle d’accès et activation

Liaisons ACP configurées

WhatsApp prend en charge les liaisons ACP persistantes avec les entrées de premier niveau 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 discussions directes correspondent aux numéros E.164 tels que +15555550123.
• Les groupes correspondent aux JID de groupes WhatsApp tels que 120363424282127706@g.us.
• Les allowlists de groupes, la politique d’expéditeur et les contrôles de mention ou d’activation s’exécutent avant qu’OpenClaw ne garantisse l’existence de la session ACP configurée.
• Une liaison ACP configurée qui correspond possède la route. Les groupes de diffusion WhatsApp ne redistribuent pas ce tour aux sessions WhatsApp ordinaires.

Comportement du numéro personnel et de l’auto-discussion

Lorsque le numéro personnel lié est également présent dans allowFrom, les protections d’auto-discussion WhatsApp s’activent :

• ignorer les accusés de lecture pour les tours d’auto-discussion
• ignorer le comportement de déclenchement automatique par mention-JID qui vous mentionnerait sinon vous-même
• si messages.responsePrefix n’est pas défini, les réponses d’auto-discussion utilisent par défaut [{identity.name}] ou [openclaw]

Normalisation des messages et contexte

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

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

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

Livraison, découpage et médias

Citation de réponse

WhatsApp prend en charge la citation native des réponses, où les réponses sortantes citent visiblement le message entrant. Contrôlez-la avec channels.whatsapp.replyToMode.

La valeur par défaut est "off". Les remplacements par compte utilisent 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 sur WhatsApp :

Par défaut : "minimal".

Les remplacements par compte utilisent channels.whatsapp.accounts.<id>.reactionLevel.

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

Réactions d’accusé

WhatsApp prend en charge les réactions d’accusé immédiates à la réception entrante via channels.whatsapp.ackReaction. Les réactions d’accusé sont contrôlées par reactionLevel — elles sont supprimées lorsque reactionLevel vaut "off".

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

Notes de comportement :

• envoyé immédiatement après l’acceptation de l’entrée entrante (avant la réponse)
• si ackReaction est présent sans emoji, WhatsApp utilise l’emoji d’identité de l’agent routé, avec repli sur "👀" ; omettez ackReaction ou définissez emoji: "" pour n’envoyer aucune réaction d’accusé de réception
• les échecs sont journalisés mais ne bloquent pas la livraison normale de la réponse
• le mode de groupe mentions réagit aux tours déclenchés par une mention ; l’activation de groupe always sert de contournement pour cette vérification
• WhatsApp utilise channels.whatsapp.ackReaction (l’ancien messages.ackReaction n’est pas utilisé 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 pendant un tour au lieu de laisser un emoji de reçu statique. Lorsque cette option est activée, OpenClaw utilise le même emplacement de réaction au message entrant pour les états du cycle de vie comme en file d’attente, réflexion, activité d’outil, Compaction, terminé et erreur.

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

Notes de comportement :

• channels.whatsapp.ackReaction contrôle toujours si les réactions d’état sont éligibles pour les messages directs et les groupes.
• La réaction d’état en file d’attente utilise le même emoji d’accusé de réception effectif que les réactions d’accusé de réception simples.
• WhatsApp dispose d’un seul emplacement de réaction de bot par message, donc les mises à jour du cycle de vie remplacent la réaction actuelle sur place.
• messages.removeAckAfterReply: true efface la réaction d’état finale après le délai configuré pour terminé/erreur.
• Les catégories d’emoji d’outil incluent tool, coding, web, deploy, build et concierge.

Comptes multiples et identifiants

Outils, actions et écritures de configuration

• La prise en charge des outils d’agent inclut l’action de réaction WhatsApp (react).
• Garde-fous d’action :
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Les écritures de configuration initiées par le canal sont activées par défaut (désactivez 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>

Prompts système

WhatsApp prend en charge les prompts système de style Telegram pour les groupes et les discussions directes via les cartes groups et direct.

Hiérarchie de résolution pour les messages de groupe :

La carte groups effective est déterminée en premier : si le compte définit ses propres groups, elle remplace entièrement la carte groups racine (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante :

1. Prompt système propre au groupe (groups["<groupId>"].systemPrompt) : utilisé lorsque l’entrée du groupe spécifique existe dans la carte et que sa clé systemPrompt est définie. Si systemPrompt est une chaîne vide (""), le caractère générique est supprimé et aucun prompt système n’est appliqué.
2. Prompt système générique de groupe (groups["*"].systemPrompt) : utilisé lorsque l’entrée du groupe spécifique est totalement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé systemPrompt.

Hiérarchie de résolution pour les messages directs :

La carte direct effective est déterminée en premier : si le compte définit son propre direct, il remplace entièrement la carte direct racine (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante :

1. Prompt système propre au direct (direct["<peerId>"].systemPrompt) : utilisé lorsque l’entrée du pair spécifique existe dans la carte et que sa clé systemPrompt est définie. Si systemPrompt est une chaîne vide (""), le caractère générique est supprimé et aucun prompt système n’est appliqué.
2. Prompt système générique de direct (direct["*"].systemPrompt) : utilisé lorsque l’entrée du pair spécifique est totalement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé systemPrompt.

Différence avec le comportement multi-compte de Telegram : Dans Telegram, la racine groups est volontairement supprimée pour tous les comptes dans une configuration multi-compte, même les comptes qui ne définissent pas leurs propres groups, afin d’empêcher un bot de recevoir des messages de groupe pour des groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection : les groups racine et direct racine sont toujours hérités par les comptes qui ne définissent pas de remplacement au niveau du compte, quel que soit le nombre de comptes configurés. Dans une configuration WhatsApp multi-compte, si vous voulez des prompts de groupe ou directs par compte, définissez explicitement la carte complète sous chaque compte plutôt que de vous appuyer sur des valeurs par défaut au niveau racine.

Comportement important :

• channels.whatsapp.groups est à la fois une carte de configuration par groupe et la liste d’autorisation des groupes au niveau de la discussion. À la portée racine ou compte, groups["*"] signifie « tous les groupes sont admis » pour cette portée.
• N’ajoutez un systemPrompt de groupe générique que lorsque vous voulez déjà que cette portée admette tous les groupes. Si vous voulez toujours que seul un ensemble fixe d’identifiants de groupe soit éligible, n’utilisez pas groups["*"] pour la valeur de prompt par défaut. Répétez plutôt le prompt sur chaque entrée de groupe explicitement autorisée.
• L’admission du groupe et l’autorisation de l’expéditeur sont des vérifications distinctes. groups["*"] élargit l’ensemble des groupes qui peuvent atteindre le traitement de groupe, mais n’autorise pas à lui seul chaque expéditeur dans ces groupes. L’accès des expéditeurs reste contrôlé séparément par channels.whatsapp.groupPolicy et channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct n’a pas le même effet secondaire pour les DM. direct["*"] fournit seulement une configuration par défaut de discussion directe après qu’un DM a déjà été admis par dmPolicy plus allowFrom ou les règles du magasin d’appairage.

Exemple :

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Pointeurs de référence de configuration

Référence principale :

• Référence de configuration - WhatsApp

Champs WhatsApp à fort signal :

• accès : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• livraison : textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-compte : accounts.<id>.enabled, accounts.<id>.authDir, remplacements au niveau du compte
• opérations : configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportement de session : session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts : groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Connexe

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