WhatsApp

Status: productierijp via WhatsApp Web (Baileys). De gateway beheert de gekoppelde sessie(s); er is geen afzonderlijk Twilio WhatsApp-kanaal.

Installeren

openclaw onboard en openclaw channels add --channel whatsapp vragen om de plugin te installeren wanneer je deze voor het eerst selecteert; openclaw channels login --channel whatsapp biedt dezelfde installatiestroom als de plugin ontbreekt. Ontwikkelcheck-outs gebruiken het lokale pluginpad; stabiele/bèta-installaties installeren eerst @openclaw/whatsapp vanuit ClawHub en vallen terug op npm. De WhatsApp-runtime wordt buiten het kernpakket van OpenClaw op npm geleverd, zodat de runtime-afhankelijkheden bij de externe plugin blijven. Handmatige installatie:

openclaw plugins install clawhub:@openclaw/whatsapp

Gebruik het kale npm-pakket (@openclaw/whatsapp) alleen voor de registerfallback; zet een exacte versie alleen vast voor een reproduceerbare installatie.

Snelle configuratie

{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>

Implementatiepatronen

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

Runtimemodel

• De gateway beheert de WhatsApp-socket en de herverbindingslus.
• Een watchdog volgt twee signalen onafhankelijk: ruwe WhatsApp Web-transportactiviteit en activiteit van applicatieberichten. Een stille maar verbonden sessie wordt niet opnieuw gestart alleen omdat er onlangs geen bericht is binnengekomen; een herverbinding wordt alleen afgedwongen wanneer er gedurende een vast intern venster (niet door de gebruiker configureerbaar) geen transportframes meer binnenkomen of applicatieberichten langer dan 4x de normale berichttime-out uitblijven. Direct na een herverbinding voor een onlangs actieve sessie gebruikt dat eerste venster de kortere normale berichttime-out in plaats van het 4x-venster. OpenClaw kan automatisch antwoorden op offlineberichten die Baileys vroeg tijdens die herverbinding aflevert, begrensd door de levensduur van de deduplicatie van inkomende bericht-ID's; bij de eerste opstart blijft de korte beveiliging tegen verouderde geschiedenis actief.
• Voor uitgaande verzendingen is een actieve WhatsApp-listener voor het doelaccount vereist; anders mislukken verzendingen direct.
• Groepsverzendingen voegen systeemeigen vermeldingsmetagegevens toe voor @+<digits>- en @<digits>-tokens (in tekst en mediabijschriften) wanneer het token overeenkomt met de huidige metagegevens van deelnemers, ook voor groepen op basis van LID.
• Status- en broadcastchats (@status, @broadcast) worden genegeerd.
• Directe chats gebruiken DM-sessieregels (session.dmScope; de standaardwaarde main voegt DM's samen in de hoofdsessie van de agent). Groepssessies worden per JID geïsoleerd (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters kunnen expliciete uitgaande doelen zijn via hun systeemeigen @newsletter-JID, waarbij kanaalsessiemetagegevens (agent:<agentId>:whatsapp:channel:<jid>) worden gebruikt in plaats van DM-semantiek.
• Het WhatsApp Web-transport respecteert standaard proxy-omgevingsvariabelen op de gatewayhost (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, varianten in kleine letters). Geef de voorkeur aan proxyconfiguratie op hostniveau boven instellingen per kanaal.

De huidige aanvrager bellen met MeowCaller (experimenteel)

De plugin kan whatsapp_call beschikbaar stellen in agentbeurten die vanuit WhatsApp zijn gestart. De plugin gebruikt MeowCaller om een WhatsApp-spraakoproep naar de huidige geautoriseerde aanvrager te plaatsen en na beantwoording een OpenClaw-TTS-bericht af te spelen. De tool heeft geen parameter voor het bestemmingsnummer, zodat een prompt de oproep niet kan omleiden. Standaard uitgeschakeld.

{"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"

Beperkingen: uitsluitend één-op-één uitgaande audio-oproepen, geen willekeurige bestemmingsnummers, geen gedeelde authenticatie met de chatverbinding, geen oproepen naar zichzelf vanuit de modus voor een persoonlijk nummer/zelfchat, gesynthetiseerde audio beperkt tot 60 seconden, geen ontvangstbevestiging voor hoorbaarheid aan de telefoonkant behalve de voltooiing van beantwoorden/afspelen/ophangen door MeowCaller, en OpenClaw stopt het begeleidende proces na een begrensd venster van 115-175 seconden (voor de verbindings-, beantwoordings-, afspeel- en afsluitfasen van MeowCaller).

Goedkeuringsprompts

WhatsApp kan goedkeuringsprompts voor uitvoering en plugins weergeven als 👍-/👎-reacties, geregeld door de configuratie voor het doorsturen van goedkeuringen op het hoogste niveau:

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

approvals.exec en approvals.plugin zijn onafhankelijk; als WhatsApp als kanaal wordt ingeschakeld, wordt alleen het transport gekoppeld en wordt niets verzonden tenzij de overeenkomende goedkeuringsfamilie is ingeschakeld en ernaartoe wordt gerouteerd. De sessiemodus levert systeemeigen emoji-goedkeuringen alleen voor goedkeuringen die vanuit WhatsApp afkomstig zijn. De doelmodus gebruikt de gedeelde doorstuurpijplijn voor expliciete doelen en maakt geen afzonderlijke fan-out naar DM's van goedkeurders.

Voor WhatsApp-goedkeuringsreacties zijn expliciete goedkeurders vereist in allowFrom (of "*"). defaultTo stelt gewone standaardberichtdoelen in, geen lijst met goedkeurders. Handmatige /approve-opdrachten doorlopen vóór de afhandeling van de goedkeuring nog steeds het normale autorisatiepad voor WhatsApp-afzenders.

Reacties op vragen

Voor een ask_user-prompt met één niet-geheime vraag met enkele keuze en één tot vier opties toont WhatsApp 1️⃣ tot en met 4️⃣ naast de optielabels. Reageer op de afgeleverde prompt met het overeenkomende nummer om de vraag te beantwoorden. OpenClaw koppelt het nummer via de Gateway aan de canonieke optie; verouderde of dubbele tikken worden genegeerd. Prompts met meerdere vragen, meerdere selecties of vrije tekst blijven uitsluitend via een tekstantwoord te beantwoorden. De normale toelatingsregels voor WhatsApp-DM's/-groepen autoriseren de reagerende afzender.

Plugin-hooks en privacy

Inkomende WhatsApp-berichten kunnen persoonlijke inhoud, telefoonnummers, groeps-ID's, namen van afzenders en velden voor sessiecorrelatie bevatten. WhatsApp zendt inkomende message_received-hookpayloads niet uit naar plugins, tenzij je je hiervoor aanmeldt:

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

Beperk de aanmelding tot één account onder channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Schakel dit alleen in voor plugins die je vertrouwt met inkomende WhatsApp-inhoud en -ID's.

Toegangsbeheer en activering

Geconfigureerde ACP-bindingen

WhatsApp ondersteunt permanente ACP-bindingen via bindings[] op het hoogste niveau:

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

Directe chats komen overeen met E.164-nummers; groepen komen overeen met WhatsApp-groeps-JID's. Groepstoelatingslijsten, afzenderbeleid en vermeldings-/activeringscontroles worden uitgevoerd voordat OpenClaw ervoor zorgt dat de gebonden ACP-sessie bestaat. Een overeenkomende binding beheert de route — broadcastgroepen waaieren die beurt niet uit naar gewone WhatsApp-sessies.

Gedrag voor persoonlijke nummers en chats met jezelf

Wanneer het gekoppelde eigen nummer ook aanwezig is in allowFrom, worden beveiligingen voor chats met jezelf geactiveerd: leesbevestigingen voor beurten in chats met jezelf worden overgeslagen, automatisch activeringsgedrag op basis van vermeldings-JID's dat jezelf zou pingen wordt genegeerd en antwoorden vallen standaard terug op [{identity.name}] (of [openclaw]) wanneer responsePrefix voor het kanaal/account niet is ingesteld.

Berichtnormalisatie en context

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

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

Bezorging, opdelen en media

Antwoorden citeren

channels.whatsapp.replyToMode regelt het native citeren van antwoorden (uitgaande antwoorden citeren zichtbaar het inkomende bericht):

Overschrijving per account: channels.whatsapp.accounts.<id>.replyToMode.

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

Reactieniveau

channels.whatsapp.reactionLevel regelt hoe ruim de agent emoji-reacties gebruikt:

Overschrijving per account: channels.whatsapp.accounts.<id>.reactionLevel.

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

Bevestigingsreacties

channels.whatsapp.ackReaction verzendt onmiddellijk een reactie bij ontvangst van een inkomend bericht, beperkt door reactionLevel (onderdrukt wanneer "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // altijd | vermeldingen | nooit      },    },  },}

Opmerkingen: wordt onmiddellijk verzonden nadat het inkomende bericht is geaccepteerd (vóór het antwoord); als ackReaction aanwezig is zonder emoji, gebruikt WhatsApp de identiteitsemoji van de gerouteerde agent, met "👀" als terugval (laat ackReaction weg of stel emoji: "" in voor geen bevestiging); fouten worden geregistreerd maar blokkeren de bezorging van het antwoord niet; groepsmodus mentions reageert alleen op beurten die door een vermelding zijn geactiveerd, terwijl groepsactivering always die controle omzeilt; WhatsApp gebruikt alleen channels.whatsapp.ackReaction (verouderde messages.ackReaction is hier niet van toepassing).

Levenscyclusstatusreacties

Stel messages.statusReactions.enabled: true in om WhatsApp tijdens een beurt de bevestigingsreactie te laten vervangen in plaats van een statische ontvangstemoji te laten staan, waarbij statussen zoals in de wachtrij, nadenken, toolactiviteit, Compaction, voltooid en fout worden doorlopen:

{  messages: {    statusReactions: {      enabled: true,    },  },}

Opmerkingen: channels.whatsapp.ackReaction bepaalt nog steeds of privéberichten en groepen in aanmerking komen; de status in de wachtrij gebruikt dezelfde effectieve emoji als gewone bevestigingsreacties; WhatsApp heeft één botreactiepositie per bericht, dus levenscyclusupdates vervangen de huidige reactie ter plaatse en herstellen de bevestiging na de definitieve status voltooid/fout.

Meerdere accounts en aanmeldgegevens

Tools, acties en configuratieschrijfbewerkingen

• Ondersteuning voor agenttools omvat de WhatsApp-reactieactie (react).
• Actiepoorten: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (bestaande acties hebben standaard true), channels.whatsapp.actions.calls (standaard false, zie MeowCaller hierboven).
• Door het kanaal geïnitieerde configuratieschrijfbewerkingen zijn standaard ingeschakeld; schakel ze uit via channels.whatsapp.configWrites: false.

Probleemoplossing

openclaw channels login --channel whatsappopenclaw channels status

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>

Systeemprompts

WhatsApp ondersteunt systeemprompts in Telegram-stijl voor groepen en directe chats via de maps groups en direct.

Resolutie voor groepsberichten: eerst wordt de effectieve map groups bepaald — als het account zelf überhaupt een sleutel groups definieert, vervangt die de hoofdmap groups volledig (geen diepe samenvoeging). Daarna wordt de prompt opgezocht in die ene resulterende map:

1. Groepsspecifieke prompt (groups["<groupId>"].systemPrompt): wordt gebruikt wanneer de groepsvermelding bestaat en de sleutel systemPrompt ervan is gedefinieerd. Een lege tekenreeks ("") onderdrukt het jokerteken en past geen prompt toe.
2. Prompt met groepsjokerteken (groups["*"].systemPrompt): wordt gebruikt wanneer de specifieke groepsvermelding ontbreekt of bestaat zonder een sleutel systemPrompt.

Resolutie voor directe berichten volgt hetzelfde patroon voor de map direct en direct["*"].

Verschil met Telegram: Telegram onderdrukt de hoofdwaarde groups voor elk account in een configuratie met meerdere accounts (zelfs voor accounts zonder eigen groups) om te voorkomen dat een bot groepsberichten ontvangt voor groepen waarvan deze geen lid is. WhatsApp past die beveiliging niet toe — hoofdwaarden groups/direct worden overgenomen door elk account zonder eigen overschrijving, ongeacht het aantal accounts. Definieer in een WhatsApp-configuratie met meerdere accounts de volledige map expliciet onder elk account als je prompts per account wilt.

Belangrijk gedrag:

• channels.whatsapp.groups is zowel een configuratiemap per groep als de toelatingslijst voor groepen op chatniveau. Op hoofd- of accountniveau betekent groups["*"] voor dat bereik "alle groepen worden toegelaten".
• Voeg alleen een jokerteken systemPrompt toe als je al wilt dat dat bereik alle groepen toelaat. Om alleen een vaste set groeps-id's in aanmerking te laten komen, herhaal je de prompt bij elke expliciet toegelaten vermelding in plaats van groups["*"] te gebruiken.
• Groepstoelating en afzenderautorisatie zijn afzonderlijke controles. groups["*"] breidt uit welke groepen door de groepsafhandeling worden verwerkt; het autoriseert niet elke afzender in die groepen — dat blijft geregeld door groupPolicy/groupAllowFrom.
• channels.whatsapp.direct heeft geen gelijkwaardig neveneffect voor privéberichten: direct["*"] levert alleen een standaardconfiguratie nadat een privébericht al is toegelaten door dmPolicy plus allowFrom of regels voor de koppelingsopslag.

Voorbeeld:

{  channels: {    whatsapp: {      groups: {        // Alleen gebruiken als alle groepen op hoofdniveau moeten worden toegelaten.        // Geldt voor alle accounts die geen eigen groups-map definiëren.        "*": { systemPrompt: "Standaardprompt voor alle groepen." },      },      direct: {        // Geldt voor alle accounts die geen eigen direct-map definiëren.        "*": { systemPrompt: "Standaardprompt voor alle directe chats." },      },      accounts: {        work: {          groups: {            // Dit account definieert zijn eigen groups, waardoor groups op hoofdniveau            // volledig worden vervangen. Definieer "*" hier ook expliciet om een jokerteken te behouden.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Richt je op projectmanagement.",            },            // Alleen gebruiken als alle groepen in dit account moeten worden toegelaten.            "*": { systemPrompt: "Standaardprompt voor werkgroepen." },          },          direct: {            // Dit account definieert zijn eigen direct-map, waardoor direct-vermeldingen op hoofdniveau            // volledig worden vervangen. Definieer "*" hier ook expliciet om een jokerteken te behouden.            "+15551234567": { systemPrompt: "Prompt voor een specifieke directe werkchat." },            "*": { systemPrompt: "Standaardprompt voor directe werkchats." },          },        },      },    },  },}

Verwijzingen naar het configuratieoverzicht

Primaire verwijzing: Configuratieoverzicht - WhatsApp

Gerelateerd

• Koppelen
• Groepen
• Beveiliging
• Kanaalroutering
• Routering met meerdere agents
• Probleemoplossing