Skip to main content
This enables you to use WhatsApp Cloud to securely connect with your local computer via the gateway. The WhatsApp Cloud adapter uses Meta’s WhatsApp Cloud API. It runs a local webhook server and sends outbound replies via the Graph API. Important: WhatsApp Cloud bots use a phone number, not a separate bot identity. We strongly recommend using a dedicated SIM/number for the bot. Otherwise, anyone who messages your regular WhatsApp number can potentially interact with the bot and access whatever it can access.

​
Requirements

  • A WhatsApp Cloud app in Meta Business Manager.
  • access_token and phone_number_id from the app.
  • A webhook endpoint that Meta can reach.

​
Create the WhatsApp Cloud app (quick steps)

  1. In Meta Business Manager, create a Meta app and add the WhatsApp product.
  2. In WhatsApp > API Setup, copy the Phone Number ID.
  3. Generate an access token (temporary for testing, or a long‑lived system user token for production).
  4. Pick a verify token (random string) you will use for webhook verification.
  5. You will need a public HTTPS URL for the webhook (use a tunnel if running locally).

​
Basic configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allow_from": [],
      "groups": [],
      "require_mention": true,
      "cloud": {
        "enabled": true,
        "verify_token": "<verify-token>",
        "app_secret": "<meta-app-secret>",
        "access_token": "<access-token>",
        "phone_number_id": "<phone-number-id>",
        "webhook_bind": "127.0.0.1:8088"
      }
    }
  }
}
WhatsApp Cloud requires a public HTTPS webhook endpoint. The safest pattern is:
  • Keep the gateway local-only.
  • Expose only the webhook port through a tunnel (ngrok/Tailscale/Cloudflare Tunnel).
{
  "gateway": {
    "bind": "loopback",
    "public_access": false,
    "auth": { "mode": "token", "token": "<gateway-token>" }
  },
  "channels": {
    "whatsapp": {
      "enabled": true,
      "cloud": {
        "enabled": true,
        "verify_token": "<verify-token>",
        "app_secret": "<meta-app-secret>",
        "access_token": "<access-token>",
        "phone_number_id": "<phone-number-id>",
        "webhook_bind": "127.0.0.1:8088"
      }
    }
  }
}
Example ngrok command (maps public HTTPS to local webhook): 
ngrok http 8088
Set your Meta webhook URL to the HTTPS URL ngrok gives you plus /webhook.

​
Webhook setup

  • The gateway listens on http://<host>:8088/webhook by default.
  • Meta will send a verification request with hub.verify_token.
  • The adapter replies with the provided challenge when the token matches.
  • For webhook POSTs, set cloud.app_secret to verify X-Hub-Signature-256 and prevent forged requests.
  • In Meta’s webhook settings, subscribe to message events for the WhatsApp product.

​
Pairing and allowlists

WhatsApp uses the shared pairing and allowlist rules. See Security and pairing.

​
Security tips

  • Keep gateway.public_access=false; only tunnel the webhook port, not the gateway.
  • Use a random verify_token and store it safely.
  • Use pairing.dm_policy=pairing unless you have a controlled, allowlisted setup.

​
Notes

  • The webhook_bind must be reachable by Meta (often via a tunnel or reverse proxy).