WhatsApp

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

Installatie

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, met npm als terugvaloptie. De WhatsApp-runtime wordt buiten het OpenClaw-kernpakket op npm geleverd, zodat de runtimeafhankelijkheden bij de externe plugin blijven. Handmatige installatie:

openclaw plugins install clawhub:@openclaw/whatsapp

Gebruik het kale npm-pakket (@openclaw/whatsapp) alleen voor de terugval naar het register; 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 lus voor opnieuw verbinden.
• Een watchdog volgt twee signalen onafhankelijk: onbewerkte transportactiviteit van WhatsApp Web en activiteit van applicatieberichten. Een stille maar verbonden sessie wordt niet opnieuw gestart alleen omdat er onlangs geen bericht is binnengekomen; opnieuw verbinden wordt alleen afgedwongen wanneer er gedurende een vast intern tijdvenster (niet door de gebruiker configureerbaar) geen transportframes binnenkomen of applicatieberichten langer dan 4x de normale berichttime-out uitblijven. Direct na opnieuw verbinden voor een onlangs actieve sessie gebruikt dat eerste tijdvenster 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 start blijft de korte beveiliging tegen verouderde geschiedenis van kracht.
• De sockettimings van Baileys zijn expliciet ingesteld onder web.whatsapp.*: keepAliveIntervalMs (pinginterval van de applicatie), connectTimeoutMs (time-out voor de openingshandshake), defaultQueryTimeoutMs (wachttijden voor Baileys-query's, plus de time-outs van OpenClaw voor uitgaand verzenden/aanwezigheid en inkomende leesbevestigingen).
• Voor uitgaande verzendingen is een actieve WhatsApp-listener voor het doelaccount vereist; anders mislukken verzendingen onmiddellijk.
• Groepsverzendingen voegen systeemeigen vermeldingsmetagegevens toe voor tokens @+<digits> en @<digits> (in tekst en mediabijschriften) wanneer het token overeenkomt met actuele metagegevens van deelnemers, inclusief groepen die door LID worden ondersteund.
• Status- en broadcastchats (@status, @broadcast) worden genegeerd.
• Directe chats gebruiken de sessieregels voor DM's (session.dmScope; standaard voegt main DM's samen in de hoofdsessie van de agent). Groepssessies worden per JID geïsoleerd (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp-kanalen/nieuwsbrieven 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 proxyomgevingsvariabelen op de Gateway-host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, varianten in kleine letters). Geef de voorkeur aan proxyconfiguratie op hostniveau boven instellingen per kanaal.
• Als messages.removeAckAfterReply is ingeschakeld, verwijdert OpenClaw de bevestigingsreactie zodra een zichtbaar antwoord is afgeleverd.

De huidige aanvrager bellen met MeowCaller (experimenteel)

De plugin kan whatsapp_call beschikbaar stellen tijdens agentbeurten die vanuit WhatsApp afkomstig zijn. Deze 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: alleen éé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 op de handset buiten de voltooiing van beantwoorden/afspelen/ophangen door MeowCaller, en OpenClaw stopt het begeleidende proces na een begrensd venster van 115-175 seconden (voor de fasen verbinding, beantwoorden, afspelen en afsluiten van MeowCaller).

Goedkeuringsprompts

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

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

approvals.exec en approvals.plugin zijn onafhankelijk; WhatsApp als kanaal inschakelen koppelt alleen het transport en verzendt niets, tenzij de overeenkomende goedkeuringscategorie is ingeschakeld en daarheen 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 uitwaaiering 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 opdrachten /approve doorlopen vóór het afhandelen van de goedkeuring nog steeds het normale WhatsApp-autorisatiepad voor afzenders.

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 hookpayloads message_received niet naar plugins uit, 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. Groepstoestemmingslijsten, afzenderbeleid en voorwaarden voor vermelding/activering worden uitgevoerd voordat OpenClaw waarborgt dat de gebonden ACP-sessie bestaat. Een overeenkomende binding beheert de route — broadcastgroepen verspreiden die beurt niet naar gewone WhatsApp-sessies.

Gedrag voor het persoonlijke nummer en de chat met jezelf

Wanneer het gekoppelde eigen nummer ook voorkomt in allowFrom, worden beveiligingen voor chats met jezelf geactiveerd: leesbevestigingen voor beurten in de chat met jezelf worden overgeslagen, automatische activering via vermeldings-JID's die jezelf zouden pingen wordt genegeerd en antwoorden gaan standaard naar [{identity.name}] (of [openclaw]) wanneer messages.responsePrefix niet is ingesteld.

Berichtnormalisatie en context

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

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

Aflevering, opsplitsing en media

Antwoorden citeren

channels.whatsapp.replyToMode beheert native citeren in antwoorden (uitgaande antwoorden citeren zichtbaar het inkomende bericht):

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

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

Reactieniveau

channels.whatsapp.reactionLevel bepaalt hoe breed de agent emoji-reacties gebruikt:

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

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

Bevestigingsreacties

channels.whatsapp.ackReaction verzendt direct na ontvangst van een inkomend bericht een reactie, afhankelijk van reactionLevel (onderdrukt wanneer "off"):

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

Opmerkingen: wordt direct 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 gelogd maar blokkeren de aflevering van antwoorden niet; groepsmodus mentions reageert alleen bij beurten die door een vermelding zijn geactiveerd, terwijl groepsactivering always die controle omzeilt; WhatsApp gebruikt uitsluitend channels.whatsapp.ackReaction (verouderde messages.ackReaction is hier niet van toepassing).

Reacties op levenscyclusstatus

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 toestanden zoals in de wachtrij, nadenken, toolactiviteit, Compaction, voltooid en fout worden doorlopen:

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

Opmerkingen: channels.whatsapp.ackReaction bepaalt nog steeds of directe berichten en groepen in aanmerking komen; de wachtrijstatus gebruikt dezelfde effectieve emoji als gewone bevestigingsreacties; WhatsApp heeft per bericht één reactievak voor de bot, zodat levenscyclusupdates de huidige reactie ter plaatse vervangen; messages.removeAckAfterReply: true wist de uiteindelijke statusreactie na de geconfigureerde wachttijd voor voltooid/fout; categorieën voor toolemoji's omvatten tool, coding, web, deploy, build en concierge.

Meerdere accounts en inloggegevens

Tools, acties en configuratieschrijfbewerkingen

• Ondersteuning voor agenttools omvat de WhatsApp-reactieactie (react).
• Actiepoorten: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (bestaande acties gebruiken 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

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

Systeemprompts

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

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

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 zonder sleutel systemPrompt bestaat.

De resolutie voor directe berichten volgt hetzelfde patroon voor de toewijzing direct en direct["*"].

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

Belangrijk gedrag:

• channels.whatsapp.groups is zowel een configuratietoewijzing per groep als de toelatingslijst voor groepen op chatniveau. Op hoofd- of accountniveau betekent groups["*"] dat "alle groepen worden toegelaten" voor dat bereik.
• Voeg alleen een jokerteken systemPrompt toe wanneer je al wilt dat dit bereik alle groepen toelaat. Om alleen een vaste verzameling 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["*"] verruimt welke groepen de groepsverwerking bereiken; het autoriseert niet elke afzender in die groepen — dat blijft geregeld door groupPolicy/groupAllowFrom.
• channels.whatsapp.direct heeft geen vergelijkbaar neveneffect voor directe berichten: direct["*"] levert alleen een standaardconfiguratie nadat een direct bericht al is toegelaten door dmPolicy plus allowFrom of regels uit de koppelingsopslag.

Voorbeeld:

{  channels: {    whatsapp: {      groups: {        // Alleen gebruiken als alle groepen op hoofdniveau moeten worden toegelaten.        // Geldt voor alle accounts die geen eigen groepentoewijzing definiëren.        "*": { systemPrompt: "Standaardprompt voor alle groepen." },      },      direct: {        // Geldt voor alle accounts die geen eigen toewijzing voor directe chats definiëren.        "*": { systemPrompt: "Standaardprompt voor alle directe chats." },      },      accounts: {        work: {          groups: {            // Dit account definieert eigen groepen, dus de hoofdgroepen worden volledig            // 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 een eigen toewijzing voor directe chats, dus directe            // hoofdvermeldingen worden volledig 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 de configuratiereferentie

Primaire referentie: Configuratiereferentie - WhatsApp

Gerelateerd

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