WhatsApp

Status: productierijp 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. Ontwikkel-checkouts gebruiken het lokale Plugin-pad; stabiele/bèta-installaties installeren eerst @openclaw/whatsapp vanuit ClawHub, met npm als terugvaloptie. 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 als terugvaloptie voor het register; zet alleen een exacte versie 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 bewakingsproces volgt twee signalen onafhankelijk: onbewerkte transportactiviteit van WhatsApp Web en activiteit van toepassingsberichten. Een stille maar verbonden sessie wordt niet opnieuw gestart alleen omdat er recent geen bericht is ontvangen; opnieuw verbinden wordt alleen afgedwongen wanneer gedurende een vast intern tijdvenster (niet door de gebruiker configureerbaar) geen transportframes binnenkomen of toepassingsberichten langer dan viermaal de normale berichttime-out uitblijven. Direct na opnieuw verbinden voor een recent actieve sessie gebruikt dat eerste tijdvenster de kortere normale berichttime-out in plaats van het viervoudige tijdvenster. OpenClaw kan automatisch antwoorden op offlineberichten die Baileys vroeg tijdens dat opnieuw verbinden aflevert, begrensd door de levensduur voor deduplicatie van inkomende bericht-ID's; bij de eerste start blijft de korte beveiliging tegen verouderde geschiedenis actief.
• De sockettimings van Baileys zijn expliciet ingesteld onder web.whatsapp.*: keepAliveIntervalMs (interval voor toepassingspings), 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.
• Bij verzendingen naar groepen worden systeemeigen vermeldingsmetagegevens gekoppeld aan tokens van de vorm @+<digits> en @<digits> (in tekst en mediabijschriften) wanneer het token overeenkomt met de actuele metagegevens van een deelnemer, inclusief groepen die door een LID worden ondersteund.
• Status- en broadcastchats (@status, @broadcast) worden genegeerd.
• Directe chats gebruiken de sessieregels voor privéberichten (session.dmScope; standaard voegt main privéberichten samen in de hoofdsessie van de agent). Groepssessies zijn 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 semantiek voor privéberichten.
• Het transport van WhatsApp Web respecteert standaard proxy-omgevingsvariabelen op de Gateway-host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY en varianten in kleine letters). Geef de voorkeur aan proxyconfiguratie op hostniveau boven instellingen per kanaal.
• Als messages.removeAckAfterReply is ingeschakeld, wist OpenClaw de bevestigingsreactie zodra een zichtbaar antwoord is afgeleverd.

De huidige aanvrager bellen met MeowCaller (experimenteel)

De Plugin kan whatsapp_call beschikbaar maken in agentbeurten die vanuit WhatsApp zijn gestart. Hiervoor wordt MeowCaller gebruikt om de huidige geautoriseerde aanvrager via WhatsApp te bellen en na het opnemen 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 uitgaande één-op-één-audio-oproepen, geen willekeurige bestemmingsnummers, geen gedeelde authenticatie met de chatverbinding, geen oproepen naar zichzelf vanuit de modus met een persoonlijk nummer/zelfchat, gesynthetiseerde audio is beperkt tot 60 seconden, geen ontvangstbevestiging van hoorbaarheid aan de toestelzijde buiten de voltooiing van opnemen/afspelen/ophangen door MeowCaller, en OpenClaw stopt het begeleidende proces na een begrensd tijdvenster van 115-175 seconden (voor de verbindings-, opname-, afspeel- en afsluitfasen van MeowCaller).

Goedkeuringsprompts

WhatsApp kan prompts voor uitvoerings- en Plugin-goedkeuring weergeven als reacties met 👍/👎, aangestuurd 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 overeenkomstige goedkeuringscategorie is ingeschakeld en daarheen wordt gerouteerd. De sessiemodus levert alleen systeemeigen emoji-goedkeuringen voor goedkeuringen die vanuit WhatsApp afkomstig zijn. De doelmodus gebruikt de gedeelde doorstuurpijplijn voor expliciete doelen en maakt geen afzonderlijke verspreiding naar privéberichten van goedkeurders.

Voor WhatsApp-goedkeuringsreacties zijn expliciete goedkeurders in allowFrom (of "*") vereist. 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-pad voor afzenderautorisatie.

Plugin-hooks en privacy

Inkomende WhatsApp-berichten kunnen persoonlijke inhoud, telefoonnummers, groepsidentificatoren, afzendernamen en velden voor sessiecorrelatie bevatten. WhatsApp zendt inkomende message_received-hookpayloads niet naar Plugins uit, tenzij je hiervoor kiest:

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

Beperk deze 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 -identificatoren.

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 toetsen voor vermelding/activering worden uitgevoerd voordat OpenClaw waarborgt dat de gebonden ACP-sessie bestaat. Een overeenkomende binding beheert de route — uitzendgroepen vertakken die beurt niet naar gewone WhatsApp-sessies.

Gedrag voor persoonlijke nummers en chats met jezelf

Wanneer het gekoppelde eigen nummer ook in allowFrom staat, worden beveiligingsmaatregelen 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 krijgen standaard het voorvoegsel [{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 } } }

Bezorging, opdelen en media

Antwoorden citeren

channels.whatsapp.replyToMode regelt het oorspronkelijke citeren bij 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 onmiddellijk een reactie bij ontvangst van een inkomend bericht, afhankelijk van reactionLevel (onderdrukt bij "off"):

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

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 terugval op "👀" (laat ackReaction weg of stel emoji: "" in voor geen bevestiging); fouten worden gelogd maar blokkeren de bezorging van antwoorden 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 (de verouderde messages.ackReaction is hier niet van toepassing).

Statusreacties tijdens de levenscyclus

Stel messages.statusReactions.enabled: true in zodat WhatsApp tijdens een beurt de bevestigingsreactie kan vervangen in plaats van een statische ontvangstemoji te laten staan, waarbij statussen zoals in 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 status in de wachtrij 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 definitieve statusreactie na de geconfigureerde wachttijd voor voltooid/fout; categorieën voor toolemoji's omvatten tool, coding, web, deploy, build en concierge.

Meerdere accounts en referenties

Hulpmiddelen, acties en configuratiewijzigingen

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

Problemen oplossen

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 groups-toewijzing bepaald — als het account überhaupt een eigen groups-sleutel 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. Jokertekenprompt voor groepen (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 hoofdconfiguratie 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 — de hoofdconfiguraties groups/direct worden overgenomen door elk account zonder eigen overschrijving, ongeacht het aantal accounts. Definieer in een WhatsApp-configuratie met meerdere accounts de volledige toewijzing expliciet onder elk account als u prompts per account wilt.

Belangrijk gedrag:

• channels.whatsapp.groups is zowel een configuratietoewijzing per groep als de toelatingslijst voor groepen op chatniveau. Op zowel hoofd- als accountniveau betekent groups["*"]: "alle groepen worden toegelaten" voor dat bereik.
• Voeg alleen een systemPrompt met jokerteken toe wanneer u al wilt dat dit bereik alle groepen toelaat. Als alleen een vaste reeks groeps-ID's in aanmerking moet komen, herhaalt u de prompt voor 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 vergelijkbaar neveneffect voor privéberichten: direct["*"] levert alleen een standaardconfiguratie nadat een privébericht al is toegelaten door dmPolicy in combinatie met allowFrom of regels uit de koppelingsopslag.

Voorbeeld:

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

Verwijzingen naar de configuratiereferentie

Primaire referentie: Configuratiereferentie - WhatsApp

Gerelateerd

• Koppelen
• Groepen
• Beveiliging
• Kanaalroutering
• Routering met meerdere agents
• Problemen oplossen