WhatsApp

​

Installeren (op aanvraag)

• Onboarding (openclaw onboard) en openclaw channels add --channel whatsapp vragen om de WhatsApp Plugin te installeren wanneer je die voor het eerst selecteert.
• openclaw channels login --channel whatsapp biedt ook de installatiestroom aan wanneer de Plugin nog niet aanwezig is.
• Dev-kanaal + git-checkout: gebruikt standaard het lokale Plugin-pad.
• Stable/Beta: installeert eerst de officiële @openclaw/whatsapp Plugin vanuit ClawHub, met npm als fallback.
• De WhatsApp-runtime wordt buiten het kernpakket van OpenClaw op npm gedistribueerd, zodat WhatsApp-specifieke runtime-afhankelijkheden bij de externe Plugin blijven.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

De huidige aanvrager bellen met MeowCaller (experimenteel)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

• alleen een-op-een uitgaande audio-oproepen
• geen willekeurige bestemmingsnummers
• geen gedeelde authenticatie met de chatverbinding
• geen zelfoproepen vanuit modus met persoonlijk nummer/zelfchat
• gesynthetiseerde audio is beperkt tot 60 seconden
• geen ontvangstbewijs voor hoorbaarheid aan handsetzijde buiten voltooiing van opnemen/afspelen/ophangen door MeowCaller
• OpenClaw stopt het begeleidende proces na een begrensd venster van 115-175 seconden, inclusief de verbindings-, opname-, afspeel- en afsluitfasen van MeowCaller

​

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 linked-device-sessie niet uitsluitend wordt herstart omdat niemand recent een bericht heeft gestuurd. Een langere limiet voor applicatiestilte forceert nog steeds een reconnect als transportframes blijven binnenkomen maar er binnen 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 beheert WhatsApp Web-applicatiepings, connectTimeoutMs beheert de time-out voor de openingshandshake, en defaultQueryTimeoutMs beheert Baileys-querywachttijden plus de lokale grenzen van OpenClaw voor uitgaand verzenden/presence en inkomende leesbevestigingsbewerkingen.
• Uitgaand verzenden vereist een actieve WhatsApp-listener voor het doelaccount.
• Groepsverzendingen voegen native vermeldingsmetadata toe voor tokens @+<digits> en @<digits> 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 linked-device-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 klapt DM’s samen naar de hoofdsessie van de agent).
• Groepssessies zijn geïsoleerd (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp-kanalen/nieuwsbrieven kunnen expliciete uitgaande doelen zijn met hun native @newsletter JID. Uitgaand verzenden naar nieuwsbrieven gebruikt 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-ackreactie nadat een zichtbare reactie is afgeleverd.

​

Goedkeuringsprompts

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

​

Plugin-hooks en privacy

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

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

​

Toegangscontrole en activering

​

Geconfigureerde ACP-bindingen

{
  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 zoals +15555550123.
• Groepen komen overeen met WhatsApp-groeps-JID’s zoals 120363424282127706@g.us.
• Groeps-allowlists, afzenderbeleid en vermeldings- of activeringscontroles worden uitgevoerd voordat OpenClaw zorgt dat de geconfigureerde ACP-sessie bestaat.
• Een overeenkomende geconfigureerde ACP-binding is eigenaar van de route. WhatsApp-uitzendgroepen verspreiden die beurt niet naar gewone WhatsApp-sessies.

​

Gedrag voor persoonlijk nummer en zelfchat

• leesbevestigingen overslaan voor zelfchatbeurten
• automatisch triggergedrag voor mention-JID negeren dat anders jezelf zou pingen
• als messages.responsePrefix niet is ingesteld, gebruiken zelfchatantwoorden 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, opdelen en media

​

Antwoordcitaat

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

​

Reactieniveau

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

​

Bevestigingsreacties

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

• direct verzonden nadat inkomend verkeer is geaccepteerd (vóór het antwoord)
• als ackReaction aanwezig is zonder emoji, gebruikt WhatsApp de identiteitsemoji van de geroute agent, met terugval naar ”👀”; laat ackReaction weg of stel emoji: "" in om geen bevestigingsreactie te verzenden
• fouten worden gelogd, maar blokkeren normale antwoordbezorging niet
• groepsmodus mentions reageert op beurten die door een vermelding zijn gestart; groepsactivatie always werkt als bypass voor deze controle
• WhatsApp gebruikt channels.whatsapp.ackReaction (legacy messages.ackReaction wordt hier niet gebruikt)

​

Lifecycle-statusreacties

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

• channels.whatsapp.ackReaction bepaalt nog steeds of statusreacties in aanmerking komen voor directe berichten en groepen.
• De statusreactie voor de wachtrij gebruikt dezelfde effectieve bevestigingsemoji als gewone bevestigingsreacties.
• WhatsApp heeft één botreactiesleuf per bericht, dus lifecycle-updates vervangen de huidige reactie op dezelfde plek.
• messages.removeAckAfterReply: true wist de uiteindelijke statusreactie na de geconfigureerde vasthoudtijd voor voltooid/fout.
• Tool-emojicategorieën omvatten tool, coding, web, deploy, build en concierge.

​

Meerdere accounts en referenties

​

Tools, acties en config-schrijfacties

• Agent-toolondersteuning omvat de WhatsApp-reactieactie (react).
• Actiegates:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Door het kanaal geïnitieerde config-schrijfacties 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 channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Systeemprompts

1. Groepsspecifieke systeemprompt (groups["<groupId>"].systemPrompt): gebruikt wanneer de specifieke groepsvermelding 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. Groepswildcard-systeemprompt (groups["*"].systemPrompt): gebruikt wanneer de specifieke groepsvermelding volledig afwezig is in de map, of wanneer deze bestaat maar geen sleutel systemPrompt definieert.

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. Directe wildcard-systeemprompt (direct["*"].systemPrompt): gebruikt wanneer de specifieke peer-vermelding volledig afwezig is in de map, of wanneer deze bestaat maar geen sleutel systemPrompt definieert.

• channels.whatsapp.groups is zowel een config-map per groep als de allowlist op chatniveau voor groepen. Op root- of accountscope betekent groups["*"] dat “alle groepen worden toegelaten” voor die scope.
• Voeg alleen een wildcard-groep systemPrompt toe wanneer je al wilt dat die scope alle groepen toelaat. Als je nog steeds alleen een vaste set groeps-ID’s in aanmerking wilt laten komen, gebruik dan geen groups["*"] voor de promptstandaard. Herhaal in plaats daarvan de prompt op elke expliciet toegestane groepsvermelding.
• Groepstoelating en afzenderautorisatie zijn afzonderlijke controles. groups["*"] verbreedt de set groepen die groepsafhandeling kan bereiken, maar autoriseert op zichzelf niet elke afzender in die groepen. Afzendertoegang wordt nog steeds afzonderlijk beheerd 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.

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

• Configuratiereferentie - WhatsApp

• toegang: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• aflevering: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• meerdere accounts: accounts.<id>.enabled, accounts.<id>.authDir, overschrijvingen op accountniveau
• bewerkingen: 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

• Koppelen
• Groepen
• Beveiliging
• Channel-routering
• Routering voor meerdere agents
• Probleemoplossing