OpenClaw WhatsApp Agent Platform

An OpenClaw plugin that connects Meta's WhatsApp Agent Platform to any configured OpenClaw agent.

Approved Channels interface

Use the accompanying distribution installer for OpenClaw 2026.9.3. The account manager appears only inside Settings → Channels → WhatsApp Agent Platform, not on the Channels overview. Installing this npm archive alone does not install the host UI integration. See the distribution INSTALL.md.

Features

• Long-polls the official WhatsApp Agent Platform updates endpoint.
• Routes each WhatsApp user either to a durable private session or to the target agent's primary session.
• Runs multiple WhatsApp Agent accounts in one plugin, each mapped to its own OpenClaw agent.
• Accepts text, voice notes, audio, images, stickers, videos, and documents.
• Uses OpenClaw's configured media-understanding providers for audio transcription and image/video description.
• Marks inbound messages as read and refreshes WhatsApp's typing indicator every 20 seconds while the agent works.
• Uploads generated audio and video to Meta and sends them as native WhatsApp media instead of exposing download links.
• Sends audio as a native WhatsApp audio attachment and supports captions on outbound videos. The Agent Platform API does not expose outbound voice-note/PTT semantics.
• Detects audio/video links in final Markdown replies (including HeyGen output) and transcodes non-Opus audio with OpenClaw's native WhatsApp voice pipeline.
• Persists offsets and message IDs to prevent backlog replay and duplicate replies.
• Stores inbound media with private filesystem permissions and validates size and SHA-256 metadata.

Outbound replies support text, audio, and video. Outbound images and documents are not implemented.

Requirements

• OpenClaw 2026.9.3 or newer in the 2026.x compatibility line.
• Node.js 24 or newer.
• A WhatsApp Agent Platform API token.
• An OpenClaw agent with a configured and usable model profile.
• Optional OpenClaw media-understanding providers for automatic transcription and image/video descriptions.

Install

After the package is published:

openclaw plugins install openclaw-whatsapp-agent-platform --pin

For local development or evaluation:

openclaw plugins install --link /absolute/path/to/openclaw-whatsapp-agent-platform

The internal plugin ID remains whatsapp-agent-admin for backward compatibility with installations created before the package became reusable.

Configure

1. Store each API token through OpenClaw's protected secret flow:

   openclaw secrets configure
   

   In multi-account mode, map each resulting SecretRef to plugins.entries.whatsapp-agent-admin.config.accounts.<accountId>.apiToken. Do not place tokens in source code, shell history, or a committed config file.

2. Configure one or more named accounts. Each account receives its own SecretRef and target agentId:

   {
     "accounts": {
       "admin": {
         "apiToken": { "source": "store", "provider": "default", "id": "WHATSAPP_ADMIN_TOKEN" },
         "agentId": "my-agent"
       },
       "sales": {
         "apiToken": { "source": "store", "provider": "default", "id": "WHATSAPP_SALES_TOKEN" },
         "agentId": "php-sales",
         "sessionMode": "main"
       },
       "projects": {
         "apiToken": { "source": "store", "provider": "default", "id": "WHATSAPP_PROJECTS_TOKEN" },
         "agentId": "php-pm",
         "sessionMode": "main"
       },
       "marketing": {
         "apiToken": { "source": "store", "provider": "default", "id": "WHATSAPP_MARKETING_TOKEN" },
         "agentId": "php-marketing",
         "sessionMode": "main"
       }
     }
   }
   

   Add this object under plugins.entries.whatsapp-agent-admin.config. The plugin resolves each workspace from the corresponding OpenClaw agent. Set workspace inside an account only when that agent does not declare one.

3. Restart and verify the Gateway:

   openclaw gateway restart
   openclaw gateway health
   openclaw plugins list
   

Configuration reference

For multi-account installations, put these fields inside accounts.<accountId>. Each account additionally accepts enabled; its state namespace defaults to whatsapp-agent-platform-<accountId>. Account IDs must contain lowercase letters, digits, underscores, or hyphens and must begin with a letter.

The top-level single-account fields remain supported for existing installations. When accounts is present, the named account configuration takes precedence.

Supported media and limits

• Images and stickers: 5 MB.
• Audio, video, and documents: 16 MB.
• Trusted media downloads are restricted to HTTPS hosts operated by WhatsApp/Meta.

If a media-understanding provider is unavailable, the private local attachment path is still supplied to the OpenClaw agent so its available tools can inspect the file.

Development

npm ci
npm run typecheck
npm test
npm pack --dry-run

The test suite exercises observable protocol behavior: polling, offsets, deduplication, typing status payloads, media download/integrity, file permissions, configuration resolution, and ambiguous send failures.

Security model

• Only inbound identities beginning with user: are routed.
• The first poll omits an offset so installation does not answer retained history.
• A send interrupted after dispatch is recorded as unknown and is not automatically retried.
• State and media files use owner-only permissions.
• The Bearer token is sent only to the Agent API and trusted Meta media-download hosts.
• Local media paths are marked private in the agent prompt and must not be repeated to the WhatsApp user.

Report suspected vulnerabilities privately to the package maintainer before public disclosure.

License

MIT

Native channel migration (0.6.0)

The registered channel ID is whatsapp-agent; whatsapp (WhatsApp Web) remains separate. Existing account configuration and protected SecretRefs remain under plugins.entries.whatsapp-agent-admin.config. No credential copying is needed.

• transport: "legacy" (default): existing service/subagent bridge; native account workers are disabled.
• transport: "channel": channel-managed polling and OpenClaw inbound dispatch; no legacy service is registered.
• Set transport at the plugin config root, not inside individual accounts.
• Keep existing state namespaces to preserve offsets and handled-message IDs.
• Native isolated sessions use the core per-account-channel-peer grammar. Old hashed sessions are preserved but are not automatically merged into the new sessions. main retains primary-session routing.
• Explicit native bindings may override the account's default agent.
• Native source metadata identifies the exact sender/account/reply destination. Platform users are not implicitly granted command-owner authorization.
• This release preserves the Agent Platform's private user: ingress boundary. It does not implement a new pairing flow, group access, or an operator allowlist. Do not deploy on an account requiring additional sender admission until that policy is implemented.
• Polling and delivery retain the bridge's local durable offset/deduplication state. This is not a claim of SDK durable-ingress-queue integration or exactly-once delivery.

Verification: npm run typecheck, npm test, npm pack --dry-run. The current openclaw plugins validate command requires tool/feature authoring metadata and does not validate this generic channel entry. Registration is exercised directly in the test suite.

Rollback: restore transport: "legacy" and restart/reload the Gateway through its supported lifecycle. Never run a separate standalone poller using the same account token.

0.8.0 — Gerenciamento de vínculos

Abra Settings → Channels → WhatsApp Agent Platform. Use + Adicionar agente, selecione um agente existente, dê um nome único à conta e selecione um segredo salvo no cofre do OpenClaw. O link Cadastrar API no cofre protegido abre /settings/secrets: cadastre o token no campo protegido, com host api.whatsapp.com, volte e clique Atualizar APIs. Tokens já vinculados não são oferecidos para novas contas para evitar dois pollers no mesmo token.

Remover vínculo pede confirmação e remove somente a conta deste plugin: o agente, histórico, estado de deduplicação e segredo no cofre são preservados. É permitido remover a última conta ou desativar todas. As alterações usam config.patch com hash de revisão; conflitos exigem atualizar a página. Nenhum token é digitado ou exibido pela página do plugin.

Local Channels UI delivery fix (2026-09-14)

This version-scoped host adaptation keeps the existing plugin accounts unchanged. The first UI patch reused an immutable asset URL, so previously cached clients could retain the original account-only screen. install-channels-cache-fix.mjs stages content-versioned manager/CSS/page assets and an entry module that registers the corrected Channels component before the host app loads its legacy lazy route. Run without arguments to stage; --apply publishes assets first, then atomically updates index.html and compressed variants, backing up the index under backups/. It refuses unexpected host entry/layout versions. Host upgrades require revalidation. Restore the backed-up index files to undo this delivery change; no account or API configuration is modified.

Validation commands:

• npm run validate — typecheck and plugin tests.
• node test/channels-integration.browser.mjs — actual host Channels renderer with isolated RPC fixtures.
• node test/channels-cache.browser.mjs — warm legacy module cache, versioned bootstrap, add/edit/remove/last-account/permissions; the app entry is a lazy-route stub, while the Channels renderer is real.
• node test/channels-boot.browser.mjs — complete real host app initialization without authenticated Gateway access.

These browser tests do not claim an authenticated production end-to-end test.