WhatsApp

Documentation Index

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

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

​

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.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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

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

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

​

Toegangscontrole en activatie

​

Gedrag met persoonlijk nummer en zelf-chat

• 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

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

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.

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.

• 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.

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