Skip to main content

WhatsApp (Business API)

ClawCentral connects to WhatsApp via the official WhatsApp Business API (Meta Cloud API). This requires a verified Meta Business account and a dedicated phone number registered as a WhatsApp Business number.

ClawCentral vs OpenClaw

The upstream OpenClaw project uses an unofficial Baileys-based connector (QR-code WebSocket pairing). ClawCentral uses the official Meta Cloud API instead — setup, credentials, and limitations are completely different.

Prerequisites​

  • A Meta Business Manager account with a verified business
  • A WhatsApp Business account linked to a dedicated phone number (cannot be a number already in use as a personal WhatsApp account)
  • A Meta Developer App with the WhatsApp product added
  • A permanent system-user access token with whatsapp_business_messaging permission

Required secrets​

Set these in Admin UI → Settings → Tenant Settings → Secrets:

SecretDescription
WHATSAPP_ACCESS_TOKENPermanent system-user access token from Meta
WHATSAPP_PHONE_NUMBER_IDPhone number ID from the WhatsApp Business dashboard
WHATSAPP_APP_SECRETApp secret (used to verify X-Hub-Signature-256 on incoming webhooks)
WHATSAPP_VERIFY_TOKENA secret string you choose; Meta sends this during webhook verification

Setup​

Step 1 — Create a Meta App​

  1. Go to developers.facebook.com and create a new app (type: Business).
  2. Add the WhatsApp product to the app.
  3. Under WhatsApp → API Setup, note your Phone Number ID and WhatsApp Business Account ID.

Step 2 — Get a permanent access token​

Temporary tokens expire after 24 hours. For production use:

  1. In Meta Business Manager, go to System Users and create a system user.
  2. Assign the system user Admin or Employee role and add it to your WhatsApp Business account.
  3. Generate a token with whatsapp_business_messaging and whatsapp_business_management permissions.
  4. Copy the token — this is your WHATSAPP_ACCESS_TOKEN.

Step 3 — Configure the webhook​

In your Meta App under WhatsApp → Configuration:

  • Callback URL: https://<your-tenant>.clawcentral.io/webhooks/whatsapp
  • Verify token: any string you choose — set the same value as WHATSAPP_VERIFY_TOKEN
  • Webhook fields to subscribe: messages

ClawCentral automatically handles the GET verification challenge and POST message delivery.

Step 4 — Set secrets in ClawCentral​

In Admin UI → Settings → Tenant Settings → Secrets, add these as key-value pairs:

  • Access Token
  • Phone Number ID
  • App Secret
  • Verify Token

Message types​

ClawCentral supports:

  • Inbound: text messages, audio (transcribed via the configured STT provider)
  • Outbound: text replies, typing indicators

Media attachments, interactive buttons, and template messages are not currently supported.

Limitations​

  • WhatsApp Business API requires messages to be initiated by the user first, or sent via approved message templates within a 24-hour window.
  • Free-tier Meta accounts have a limit of 1,000 unique users per month; production volumes require a verified business.
  • A phone number registered as a WhatsApp Business number cannot simultaneously be used as a personal WhatsApp account.
  • Number porting from personal WhatsApp to Business API deletes all existing chat history.

User identity mapping​

When a message arrives, ClawCentral maps the sender's WhatsApp phone number (wa_id) to a ClawCentral user ID using the KV key wa:{phone}. If no mapping exists, a new user entry is created automatically using the phone number as the identifier.