openclaw-whatsapp-cloud-api

v1.1.0

Published

15 days ago

WhatsApp Cloud API channel plugin for OpenClaw — official Meta Business API, no Baileys

0High
0Medium
0Low

marcocostantino

openclaw whatsapp cloud-api meta channel plugin chatbot business-api

OpenClaw WhatsApp Cloud API Channel

WhatsApp channel for OpenClaw using Meta's official Cloud API — production-safe, no Baileys, no ban risk. Supports multiple accounts (phone numbers) on a single channel.

Why this plugin?

OpenClaw's built-in WhatsApp channel uses Baileys, a reverse-engineered WhatsApp Web protocol. It works great for personal use, but Meta can ban accounts at any time — making it unsuitable for business bots.

This plugin uses the official WhatsApp Cloud API (graph.facebook.com) instead:

| | Built-in (Baileys) | This plugin (Cloud API) | |---|---|---| | Auth | QR code scan | OAuth access token | | Ban risk | High (unofficial) | None (official) | | 24-hour window | No restriction | Required (templates after 24h) | | Cost | Free | Pay-per-conversation | | Sending first | Anytime | Templates only | | Best for | Personal assistant | Customer-facing bots |

Prerequisites

OpenClaw >= 2026.2.x installed and configured (openclaw configure)
Node.js >= 22
A Meta Business App with WhatsApp product enabled
A domain with HTTPS for the webhook (ngrok for dev, reverse proxy for prod)

Quick start (development)

1. Install the plugin

git clone https://github.com/baiadigitale/openclaw-channel-whatsapp-cloud.git
cd openclaw-channel-whatsapp-cloud
npm install && npm run build
openclaw plugins install -l .

Note: Due to a known OpenClaw bug with symlinks, if the plugin isn't discovered after install -l ., add this to ~/.openclaw/openclaw.json:
{
  "plugins": {
    "load": {
      "paths": ["/absolute/path/to/openclaw-channel-whatsapp-cloud"]
    }
  }
}

2. Get Meta credentials

Go to developers.facebook.com and create an app (type: Business)
Add the WhatsApp product
In WhatsApp > API Setup, note your Phone Number ID
Create a permanent access token:
- Business Settings > System Users > create one with Admin role
- Generate a token with permissions: whatsapp_business_messaging, whatsapp_business_management
Note your App Secret from App Settings > Basic (for webhook signature verification)

3. Run the setup wizard

openclaw whatsapp-cloud setup

This will prompt for all credentials and save them to ~/.openclaw/openclaw.json.

Alternatively, set them manually:

openclaw config set channels.whatsapp-cloud.phoneNumberId "YOUR_PHONE_NUMBER_ID"
openclaw config set channels.whatsapp-cloud.accessToken "YOUR_ACCESS_TOKEN"
openclaw config set channels.whatsapp-cloud.appSecret "YOUR_APP_SECRET"
openclaw config set channels.whatsapp-cloud.verifyToken "a-random-string-you-choose"

4. Expose the webhook (dev)

ngrok http 3100

Copy the https://xxxx.ngrok-free.app URL.

5. Register the webhook on Meta

Go to WhatsApp > Configuration in your Meta app
Click Edit on the Webhook section
Callback URL: https://your-ngrok-url/webhook/whatsapp-cloud
Verify Token: the string you chose in step 3
Click Verify and Save
Subscribe to the messages webhook field

6. Start the gateway

openclaw gateway restart

Send a WhatsApp message to your business number — the bot will respond.

Multi-account setup

The plugin supports multiple WhatsApp accounts (different phone numbers) on the same channel, sharing a single webhook endpoint. Each account can be bound to a different OpenClaw agent via bindings.

Adding accounts

# Set up the first account
openclaw whatsapp-cloud setup --account personal

# Add a second account
openclaw whatsapp-cloud setup --account biz

Or via the interactive onboarding flow:

openclaw channels login whatsapp-cloud

Configuration

Multi-account config uses the accounts key. Webhook settings (webhookPort, webhookPath, verifyToken) are shared at channel level. Each account has its own credentials and policies:

{
  "channels": {
    "whatsapp-cloud": {
      // Shared settings
      "webhookPort": 3100,
      "webhookPath": "/webhook/whatsapp-cloud",
      "verifyToken": "a-random-string-you-choose",

      // Named accounts
      "accounts": {
        "personal": {
          "enabled": true,
          "phoneNumberId": "111111111111111",
          "accessToken": "EAAx...",
          "appSecret": "abc123...",
          "dmPolicy": "open",
          "sendReadReceipts": true
        },
        "biz": {
          "enabled": true,
          "phoneNumberId": "222222222222222",
          "accessToken": "EAAy...",
          "appSecret": "def456...",
          "dmPolicy": "allowlist",
          "allowFrom": ["+393491234567", "+14155551234"],
          "sendReadReceipts": true
        }
      }
    }
  },

  // Route each account to a different agent
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp-cloud", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "whatsapp-cloud", "accountId": "biz" } }
  ]
}

How routing works

Meta sends webhooks to a single endpoint (/webhook/whatsapp-cloud)
Each webhook payload contains metadata.phone_number_id identifying which number received the message
The plugin looks up the corresponding account and dispatches to the correct agent
Replies are sent using the account's own credentials

App Secret

appSecret can be set per-account or at channel level (shared fallback). If all your numbers belong to the same Meta App, set it once at channel level:

{
  "channels": {
    "whatsapp-cloud": {
      "appSecret": "shared-app-secret",
      "accounts": {
        "personal": { "phoneNumberId": "...", "accessToken": "..." },
        "biz": { "phoneNumberId": "...", "accessToken": "..." }
      }
    }
  }
}

If accounts belong to different Meta Apps, set appSecret per-account instead.

Meta webhook configuration

All phone numbers under the same Meta App share one webhook URL. You only need to configure the webhook once in Meta's dashboard, and all numbers will route through it.

If accounts span different Meta Apps, each app needs its own webhook pointing to the same endpoint.

CLI commands

# Status of all accounts
openclaw whatsapp-cloud status

# Test a specific account
openclaw whatsapp-cloud test +393491234567 --account biz

# Set up a new account
openclaw whatsapp-cloud setup --account newaccount

Backward compatibility

Existing single-account configs (flat, without accounts) continue to work as-is — they are treated as a single account named "default". No migration is required.

When you run setup --account <name> on a flat config, it is automatically migrated to multi-account format.

Production deployment

Architecture

Users on WhatsApp
      |
      v
Meta Cloud API (graph.facebook.com)
      |
      v  HTTPS POST
+--------------------------------------------------+
|  Your server (VPS / Docker / Cloud)              |
|                                                  |
|  nginx/Caddy (TLS termination, port 443)         |
|      |                                           |
|      v  proxy_pass :3100                         |
|  OpenClaw Gateway (systemd service)              |
|    +-- whatsapp-cloud plugin                     |
|    |     webhook.ts  -> receives & routes msgs   |
|    |     crypto.ts   -> verifies HMAC signature  |
|    |     config.ts   -> multi-account resolution |
|    |     index.ts    -> dispatches to agent       |
|    |     api.ts      -> sends replies             |
|    +-- agent home (Claude / GPT / ...)           |
|    +-- agent work (Claude / GPT / ...)           |
+--------------------------------------------------+

Recommended repo structure

Create a deployment repository separate from this plugin:

my-openclaw-bot/
  openclaw.json          # OpenClaw config (env var refs for secrets)
  .env.example           # Documents all required env vars
  .env                   # Actual secrets (NEVER commit this)
  .gitignore
  workspace/
    AGENTS.md            # Agent instructions, persona, behavior rules
    SOUL.md              # Personality, tone, boundaries
    IDENTITY.md          # Agent name, emoji
    USER.md              # Info about the user/company
    TOOLS.md             # Tool-specific notes
  scripts/
    deploy.sh            # Deployment automation
    backup.sh            # State backup
  docker-compose.yml     # Optional: containerized deployment
  Caddyfile              # Or nginx.conf — reverse proxy config

.gitignore:

.env
*.bak
sessions/
credentials/

openclaw.json (multi-account with env var references):

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },

  // LLM provider
  "auth": {
    "profiles": {
      "anthropic:default": {
        "provider": "anthropic",
        "mode": "token"
      }
    }
  },
  "agents": {
    "list": [
      { "id": "personal-agent", "workspace": "./workspace-personal" },
      { "id": "business-agent", "workspace": "./workspace-business" }
    ]
  },

  // WhatsApp Cloud channel — multiple accounts
  "channels": {
    "whatsapp-cloud": {
      "webhookPort": 3100,
      "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
      "appSecret": "${WHATSAPP_APP_SECRET}",
      "accounts": {
        "personal": {
          "phoneNumberId": "${WHATSAPP_PERSONAL_PHONE_ID}",
          "accessToken": "${WHATSAPP_PERSONAL_TOKEN}",
          "dmPolicy": "open",
          "sendReadReceipts": true
        },
        "business": {
          "phoneNumberId": "${WHATSAPP_BUSINESS_PHONE_ID}",
          "accessToken": "${WHATSAPP_BUSINESS_TOKEN}",
          "dmPolicy": "allowlist",
          "allowFrom": ["+393491234567"]
        }
      }
    }
  },

  // Bind each account to its agent
  "bindings": [
    { "agentId": "personal-agent", "match": { "channel": "whatsapp-cloud", "accountId": "personal" } },
    { "agentId": "business-agent", "match": { "channel": "whatsapp-cloud", "accountId": "business" } }
  ],

  // Plugin
  "plugins": {
    "entries": {
      "whatsapp-cloud": { "enabled": true }
    }
  }
}

.env.example:

# Anthropic API key (get from https://console.anthropic.com/settings/keys)
ANTHROPIC_API_KEY=sk-ant-...

# OpenClaw gateway auth token (generate: openssl rand -hex 24)
OPENCLAW_GATEWAY_TOKEN=

# WhatsApp Cloud API — shared
WHATSAPP_VERIFY_TOKEN=
WHATSAPP_APP_SECRET=

# WhatsApp Cloud API — personal account
WHATSAPP_PERSONAL_PHONE_ID=
WHATSAPP_PERSONAL_TOKEN=

# WhatsApp Cloud API — business account
WHATSAPP_BUSINESS_PHONE_ID=
WHATSAPP_BUSINESS_TOKEN=

Install on a production server

# 1. Install OpenClaw
npm install -g openclaw

# 2. Clone the plugin (private repo — no npm publish needed)
git clone [email protected]:baiadigitale/openclaw-channel-whatsapp-cloud.git ~/extensions/whatsapp-cloud
cd ~/extensions/whatsapp-cloud && npm install && npm run build

# 3. Clone your deployment repo
git clone https://github.com/yourorg/my-openclaw-bot.git ~/openclaw-bot
cd ~/openclaw-bot

# 4. Copy env file and fill in secrets
cp .env.example .env
nano .env

# 5. Point OpenClaw to your config
export OPENCLAW_CONFIG_PATH=~/openclaw-bot/openclaw.json
export OPENCLAW_STATE_DIR=~/openclaw-bot/.state

# 6. Install and start the gateway
openclaw gateway install
systemctl --user start openclaw-gateway.service
systemctl --user enable openclaw-gateway.service

Make sure your openclaw.json loads the plugin from the cloned path:

{
  "plugins": {
    "load": {
      "paths": ["~/extensions/whatsapp-cloud"]
    },
    "entries": {
      "whatsapp-cloud": { "enabled": true }
    }
  }
}

Update the plugin

After pushing changes to the repo, run this on the server:

cd ~/extensions/whatsapp-cloud && git pull && npm install && npm run build && systemctl --user restart openclaw-gateway.service

Reverse proxy (Caddy)

Caddyfile:

yourdomain.com {
    reverse_proxy /webhook/whatsapp-cloud localhost:3100
}

sudo caddy start --config Caddyfile

Caddy handles TLS automatically via Let's Encrypt.

nginx alternative:

server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location /webhook/whatsapp-cloud {
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker deployment (optional)

docker-compose.yml:

services:
  openclaw:
    image: node:22-slim
    working_dir: /app
    command: ["npx", "openclaw", "gateway", "--bind", "lan", "--port", "3100"]
    env_file: .env
    environment:
      OPENCLAW_CONFIG_PATH: /app/openclaw.json
      OPENCLAW_STATE_DIR: /data
      NODE_ENV: production
    volumes:
      - ./openclaw.json:/app/openclaw.json:ro
      - ./workspace:/app/workspace:ro
      - openclaw-data:/data
    ports:
      - "3100:3100"
    restart: unless-stopped

volumes:
  openclaw-data:

Monitoring

# Live logs
journalctl --user -u openclaw-gateway.service -f

# Channel status (shows all accounts)
openclaw whatsapp-cloud status

# Gateway health
openclaw gateway status

# Send a test message from a specific account
openclaw whatsapp-cloud test +39XXXXXXXXXX --account personal

Security checklist

[ ] appSecret is set (enables webhook HMAC signature verification)
[ ] Access token is a System User token (permanent, not a temporary test token)
[ ] dmPolicy is set to "allowlist" if the bot should only serve specific numbers
[ ] Webhook endpoint is HTTPS-only
[ ] .env file has chmod 600 and is not committed to git
[ ] Gateway auth token is set (gateway.auth.mode: "token")
[ ] Gateway binds to loopback only (reverse proxy handles external traffic)

Configuration reference

Channel-level settings (shared)

| Key | Type | Default | Description | |-----|------|---------|-------------| | enabled | boolean | true | Enable/disable the entire channel | | webhookPort | number | 3100 | HTTP server port for webhooks | | webhookPath | string | "/webhook/whatsapp-cloud" | URL path for the webhook endpoint | | verifyToken | string | "openclaw-wa-cloud-verify" | Custom token for webhook endpoint verification | | appSecret | string | — | Meta App Secret (fallback if not set per-account) | | accounts | object | — | Named accounts (see below) |

Per-account settings (`accounts.<name>.*`)

| Key | Type | Default | Description | |-----|------|---------|-------------| | enabled | boolean | true | Enable/disable this account | | phoneNumberId | string | required | WhatsApp Phone Number ID | | businessAccountId | string | — | WhatsApp Business Account ID | | accessToken | string | required | Meta API access token (system user token) | | appSecret | string | — | Per-account App Secret (overrides channel-level) | | apiVersion | string | "v21.0" | Meta Graph API version | | dmPolicy | string | "open" | "open" (anyone) or "allowlist" (restricted) | | allowFrom | string[] | [] | E.164 numbers allowed when dmPolicy=allowlist | | sendReadReceipts | boolean | true | Auto-mark incoming messages as read |

Legacy flat config (single account)

For backward compatibility, all per-account fields can also be set directly under channels.whatsapp-cloud without the accounts key. This is treated as a single account named "default".

Features

Inbound message types

Text messages
Images (with/without captions)
Audio, video, documents, stickers
Location sharing
Contact cards
Interactive replies (button and list selections)
Quoted messages (reply context)

Outbound capabilities

Text messages (auto-split at 4096 chars)
Interactive buttons (up to 3 quick reply buttons)
Interactive lists (section-based menus)
Media messages (image, audio, video, document)
Template messages (for messages outside the 24h window)
Read receipts

Security

HMAC-SHA256 webhook signature verification (via App Secret)
Timing-safe comparison to prevent timing attacks
DM policy (open / allowlist) per account
Phone number normalization for allowlist matching

The 24-hour messaging window

WhatsApp Cloud API enforces a 24-hour customer service window:

When a customer messages you, you have 24 hours to respond with free-form text
After the window closes, you can only send pre-approved template messages
Each template must be submitted to Meta for review

This plugin handles free-form responses automatically. For proactive notifications, use the sendTemplate API:

import { sendTemplate } from "@baia-digitale/whatsapp-cloud";

Development

git clone https://github.com/baiadigitale/openclaw-channel-whatsapp-cloud.git
cd openclaw-channel-whatsapp-cloud
npm install

npm run type-check    # TypeScript strict mode
npm test              # 49 tests
npm run dev           # Watch mode (auto-rebuild)

# Link to OpenClaw for development
openclaw plugins install -l .

Project structure

src/
  index.ts        — Plugin entry point + channel definition
  config.ts       — Config normalization (multi-account / legacy compat)
  types.ts        — TypeScript interfaces
  api.ts          — Meta Cloud API client (outbound)
  webhook.ts      — HTTP server (inbound webhooks, multi-account routing)
  crypto.ts       — HMAC-SHA256 signature verification
  setup.ts        — Interactive setup wizard
  onboarding.ts   — OpenClaw onboarding adapter
  runtime.ts      — OpenClaw runtime accessor
  __tests__/      — Vitest test suites

Rate limits

New WhatsApp Business accounts start at 250 unique recipients per 24 hours. As quality improves:

250 > 1,000 > 10,000 > 100,000 > unlimited

Troubleshooting

Webhook verification fails:

Ensure verifyToken in OpenClaw config matches what you entered in Meta dashboard
The webhook URL must be reachable over HTTPS

Messages not arriving:

Check that you subscribed to the messages webhook field in Meta dashboard
Check logs: journalctl --user -u openclaw-gateway.service -f
Verify appSecret is correct (wrong secret = messages silently dropped)
In multi-account mode, verify the phoneNumberId in config matches the actual phone number ID from Meta

"phoneNumberId?.trim is not a function":

The phoneNumberId was saved as a number instead of a string. Fix it in ~/.openclaw/openclaw.json by wrapping the value in quotes: "phoneNumberId": "878388375365101"

Plugin not found after install -l .:

OpenClaw has a symlink discovery bug. Add plugins.load.paths to your config pointing to the plugin directory (see install instructions above)

Gateway won't start:

Set gateway.mode: openclaw config set gateway.mode local
Check logs: journalctl --user -u openclaw-gateway.service -n 50

Messages going to wrong agent (multi-account):

Check that phoneNumberId is correct for each account in config
Verify your bindings match the accountId names in accounts
Run openclaw whatsapp-cloud status to see which accounts are active

License

MIT — Baia Digitale SRL