WhatsApp

Status: productieklaar via WhatsApp Web (Baileys). Gateway beheert gekoppelde sessie(s).

# Installeren (op aanvraag)

• Onboarding (openclaw onboard) en openclaw channels add --channel whatsapp vragen om de WhatsApp-Plugin te installeren wanneer je deze voor het eerst selecteert.
• openclaw channels login --channel whatsapp biedt ook de installatiestroom wanneer de Plugin nog niet aanwezig is.
• Dev-kanaal + git-checkout: gebruikt standaard het lokale Plugin-pad.
• Stabiel/Beta: gebruikt het npm-pakket @openclaw/whatsapp op de huidige officiële release-tag.

Handmatige installatie blijft beschikbaar:

openclaw plugins install @openclaw/whatsapp

Gebruik het kale pakket om de huidige officiële release-tag te volgen. Pin alleen een exacte versie wanneer je een reproduceerbare installatie nodig hebt.

Op Windows heeft de WhatsApp-Plugin Git nodig op PATH tijdens npm install, omdat een van de Baileys/libsignal-afhankelijkheden wordt opgehaald via een git-URL. Installeer Git for Windows, herstart daarna de shell en voer de installatie opnieuw uit:

winget install --id Git.Git -e

Portable Git werkt ook als de bin-directory ervan op PATH staat.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Implementatiepatronen

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

# Runtimemodel

• Gateway beheert de WhatsApp-socket en reconnect-lus.
• De reconnect-watchdog gebruikt WhatsApp Web-transportactiviteit, niet alleen inkomend app-berichtvolume, zodat een stille gekoppeld-apparaat-sessie niet alleen opnieuw wordt gestart omdat niemand recent een bericht heeft gestuurd. Een langere applicatiestilte-limiet forceert nog steeds een reconnect als transportframes blijven binnenkomen maar er tijdens het watchdog-venster geen applicatieberichten worden verwerkt; na een tijdelijke reconnect voor een recent actieve sessie gebruikt die applicatiestiltecontrole de normale berichttime-out voor het eerste herstelvenster.
• Baileys-sockettimings zijn expliciet onder web.whatsapp.*: keepAliveIntervalMs bepaalt WhatsApp Web-applicatiepings, connectTimeoutMs bepaalt de time-out voor de openingshandshake, en defaultQueryTimeoutMs bepaalt Baileys-querytime-outs.
• Uitgaande verzendingen vereisen een actieve WhatsApp-listener voor het doelaccount.
• Groepsverzendingen voegen native vermeldingsmetadata toe voor @+<digits>- en @<digits>-tokens in tekst en mediabijschriften wanneer het token overeenkomt met huidige WhatsApp-deelnemersmetadata, inclusief LID-ondersteunde groepen.
• Status- en broadcastchats worden genegeerd (@status, @broadcast).
• De reconnect-watchdog volgt WhatsApp Web-transportactiviteit, niet alleen inkomend app-berichtvolume: stille gekoppeld-apparaat-sessies blijven actief zolang transportframes doorgaan, maar een transportstoring forceert ruim vóór het latere pad voor externe verbreking een reconnect.
• Directe chats gebruiken DM-sessieregels (session.dmScope; standaard main vouwt DM's samen naar de hoofdsessie van de agent).
• Groepssessies zijn geïsoleerd (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters kunnen expliciete uitgaande doelen zijn met hun native @newsletter-JID. Uitgaande nieuwsbriefverzendingen gebruiken kanaalsessiemetadata (agent:<agentId>:whatsapp:channel:<jid>) in plaats van DM-sessiesemantiek.
• WhatsApp Web-transport respecteert standaard proxy-omgevingsvariabelen op de Gateway-host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varianten in kleine letters). Geef de voorkeur aan proxyconfiguratie op hostniveau boven kanaalspecifieke WhatsApp-proxyinstellingen.
• Wanneer messages.removeAckAfterReply is ingeschakeld, wist OpenClaw de WhatsApp-ack-reactie nadat een zichtbaar antwoord is afgeleverd.

# Plugin-hooks en privacy

Inkomende WhatsApp-berichten kunnen persoonlijke berichtinhoud, telefoonnummers, groepsidentificaties, afzendernamen en sessiecorrelatievelden bevatten. Daarom zendt WhatsApp inkomende message_received-hookpayloads niet uit naar plugins tenzij je dit expliciet inschakelt:

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

Je kunt de opt-in beperken tot één account:

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

Schakel dit alleen in voor plugins die je vertrouwt om inkomende WhatsApp-berichtinhoud en identificaties te ontvangen.

# Toegangscontrole en activatie

# Gedrag met persoonlijk nummer en zelf-chat

Wanneer het gekoppelde eigen nummer ook aanwezig is in allowFrom, worden WhatsApp-zelf-chatbeveiligingen geactiveerd:

• leesbevestigingen overslaan voor zelf-chatbeurten
• auto-triggergedrag voor vermeldings-JID's negeren dat anders jezelf zou pingen
• als messages.responsePrefix niet is ingesteld, gebruiken zelf-chatantwoorden standaard [{identity.name}] of [openclaw]

# Berichtnormalisatie en context

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

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

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

# Bezorging, opsplitsing en media

# Antwoordcitaat

WhatsApp ondersteunt native antwoordcitaten, waarbij uitgaande antwoorden het inkomende bericht zichtbaar citeren. Regel dit met channels.whatsapp.replyToMode.

Standaard is "off". Overschrijvingen per account gebruiken channels.whatsapp.accounts.<id>.replyToMode.

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

# Reactieniveau

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

Standaard: "minimal".

Overschrijvingen per account gebruiken channels.whatsapp.accounts.<id>.reactionLevel.

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

# Bevestigingsreacties

WhatsApp ondersteunt onmiddellijke ack-reacties bij inkomende ontvangst via channels.whatsapp.ackReaction. Ack-reacties worden begrensd door reactionLevel: ze worden onderdrukt wanneer reactionLevel "off" is.

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

Gedragsnotities:

• direct verzonden nadat inkomend verkeer is geaccepteerd (vóór antwoord)
• fouten worden gelogd maar blokkeren normale antwoordbezorging niet
• groepsmodus mentions reageert op beurten die door een vermelding worden geactiveerd; groepsactivatie always werkt als bypass voor deze controle
• WhatsApp gebruikt channels.whatsapp.ackReaction (legacy messages.ackReaction wordt hier niet gebruikt)

# Meerdere accounts en referenties

# Tools, acties en configuratieschrijfacties

• Ondersteuning voor agenttools omvat de WhatsApp-reactieactie (react).
• Actiegates:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Door het kanaal geïnitieerde configuratieschrijfacties zijn standaard ingeschakeld (uitschakelen via channels.whatsapp.configWrites=false).

# Probleemoplossing

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# Systeemprompts

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

Resolutiehiërarchie voor groepsberichten:

De effectieve map groups wordt eerst bepaald: als het account zijn eigen groups definieert, vervangt deze de rootmap groups volledig (geen diepe merge). Promptopzoeking wordt daarna uitgevoerd op de resulterende enkele map:

1. Groepsspecifieke systeemprompt (groups["<groupId>"].systemPrompt): gebruikt wanneer het specifieke groepsitem in de map bestaat en de sleutel systemPrompt ervan is gedefinieerd. Als systemPrompt een lege string ("") is, wordt de wildcard onderdrukt en wordt er geen systeemprompt toegepast.
2. Groepswildcard-systeemprompt (groups["*"].systemPrompt): gebruikt wanneer het specifieke groepsitem volledig afwezig is in de map, of wanneer het bestaat maar geen sleutel systemPrompt definieert.

Resolutiehiërarchie voor directe berichten:

De effectieve map direct wordt eerst bepaald: als het account zijn eigen direct definieert, vervangt deze de rootmap direct volledig (geen diepe merge). Promptopzoeking wordt daarna uitgevoerd op de resulterende enkele map:

1. Direct-specifieke systeemprompt (direct["<peerId>"].systemPrompt): gebruikt wanneer de specifieke peer-vermelding in de map bestaat en de sleutel systemPrompt is gedefinieerd. Als systemPrompt een lege string ("") is, wordt de wildcard onderdrukt en wordt er geen systeemprompt toegepast.
2. Direct-wildcard-systeemprompt (direct["*"].systemPrompt): gebruikt wanneer de specifieke peer-vermelding volledig ontbreekt in de map, of wanneer die wel bestaat maar geen sleutel systemPrompt definieert.

Verschil met het multi-accountgedrag van Telegram: In Telegram wordt root-groups bewust onderdrukt voor alle accounts in een multi-accountconfiguratie — zelfs accounts die zelf geen groups definiëren — om te voorkomen dat een bot groepsberichten ontvangt voor groepen waarvan hij geen lid is. WhatsApp past deze beveiliging niet toe: root-groups en root-direct worden altijd overgenomen door accounts die geen override op accountniveau definiëren, ongeacht hoeveel accounts zijn geconfigureerd. Als je in een multi-accountconfiguratie van WhatsApp prompts per account voor groepen of directe chats wilt, definieer dan de volledige map expliciet onder elk account in plaats van te vertrouwen op standaardwaarden op rootniveau.

Belangrijk gedrag:

• channels.whatsapp.groups is zowel een configuratiemap per groep als de allowlist voor groepen op chatniveau. Op root- of accountniveau betekent groups["*"] dat "alle groepen worden toegelaten" voor dat bereik.
• Voeg alleen een wildcardgroep-systemPrompt toe wanneer je al wilt dat dat bereik alle groepen toelaat. Als je nog steeds wilt dat alleen een vaste set groeps-ID's in aanmerking komt, gebruik dan niet groups["*"] als standaardwaarde voor de prompt. Herhaal de prompt in plaats daarvan op elke expliciet toegestane groepsvermelding.
• Groepstoelating en afzenderautorisatie zijn afzonderlijke controles. groups["*"] vergroot de set groepen die groepsafhandeling kunnen bereiken, maar autoriseert op zichzelf niet elke afzender in die groepen. Afzendertoegang wordt nog steeds afzonderlijk geregeld door channels.whatsapp.groupPolicy en channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct heeft niet hetzelfde neveneffect voor DM's. direct["*"] biedt alleen een standaardconfiguratie voor directe chats nadat een DM al is toegelaten door dmPolicy plus allowFrom of regels uit de pairing-store.

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.
            "[email protected]": {
              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 configuratiereferentie

Primaire referentie:

• Configuratiereferentie - WhatsApp

Belangrijke WhatsApp-velden:

• toegang: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• aflevering: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-account: accounts.<id>.enabled, accounts.<id>.authDir, overrides op accountniveau
• beheer: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• sessiegedrag: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# Gerelateerd

• Pairing
• Groepen
• Beveiliging
• Kanaalroutering
• Multi-agentroutering
• Probleemoplossing