WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Installatie (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.
• Stable/Beta: gebruikt het npm-pakket @openclaw/whatsapp wanneer een huidig pakket is gepubliceerd.

openclaw plugins install @openclaw/whatsapp

​

Snelle installatie

{
  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-loop.
• De reconnect-watchdog gebruikt WhatsApp Web-transportactiviteit, niet alleen het volume van inkomende app-berichten, zodat een stille sessie van een gekoppeld apparaat niet opnieuw wordt gestart alleen omdat niemand onlangs een bericht heeft gestuurd. Een langere limiet voor applicatiestilte forceert nog steeds een reconnect als transportframes blijven binnenkomen maar er geen applicatieberichten worden verwerkt binnen het watchdog-venster; na een tijdelijke reconnect voor een recent actieve sessie gebruikt die controle op applicatiestilte 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-querytime-outs.
• Uitgaande verzendingen vereisen een actieve WhatsApp-listener voor het doelaccount.
• Status- en broadcastchats worden genegeerd (@status, @broadcast).
• De reconnect-watchdog volgt WhatsApp Web-transportactiviteit, niet alleen het volume van inkomende app-berichten: stille sessies van gekoppelde apparaten blijven actief zolang transportframes doorgaan, maar een transportstoring forceert ruim vóór het latere externe disconnect-pad 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 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-proxy-instellingen.
• Wanneer messages.removeAckAfterReply is ingeschakeld, wist OpenClaw de WhatsApp-ack-reactie nadat een zichtbaar antwoord is afgeleverd.

​

Plugin-hooks en privacy

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

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

​

Toegangscontrole en activatie

​

Gedrag met persoonlijk nummer en chatten met jezelf

• leesbevestigingen overslaan voor beurten waarin je met jezelf chat
• auto-triggergedrag via mention-JID negeren dat anders jezelf zou pingen
• als messages.responsePrefix niet is ingesteld, gebruiken antwoorden aan jezelf 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,
        },
      },
    },
  },
}

​

Aflevering, chunking en media

​

Antwoorden citeren

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

​

Reactieniveau

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

​

Bevestigingsreacties

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

• onmiddellijk verzonden nadat inkomend is geaccepteerd (vóór het antwoord)
• fouten worden gelogd maar blokkeren normale antwoordaflevering niet
• groepsmodus mentions reageert op beurten die door een vermelding zijn 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 configuratieschrijfbewerkingen

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

​

Problemen oplossen

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

​

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. Wildcard-systeemprompt voor groepen (groups["*"].systemPrompt): gebruikt wanneer de specifieke groepsvermelding volledig ontbreekt in de map, of wanneer die bestaat maar geen sleutel systemPrompt definieert.

1. Direct-specifieke systeemprompt (direct["<peerId>"].systemPrompt): gebruikt wanneer de specifieke peervermelding 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. Wildcard-systeemprompt voor direct (direct["*"].systemPrompt): gebruikt wanneer de specifieke peervermelding volledig ontbreekt in de map, of wanneer die bestaat maar geen sleutel systemPrompt definieert.

• channels.whatsapp.groups is zowel een configuratiemap 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 wilt dat alleen een vaste set groeps-ID’s in aanmerking komt, gebruik dan niet groups["*"] voor de promptstandaard. Herhaal de prompt in plaats daarvan 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 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.

{
  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
• bezorging: 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
• instructies: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

Gerelateerd

• Koppeling
• Groepen
• Beveiliging
• Kanaalroutering
• Routering voor meerdere agents
• Probleemoplossing