All channels

WhatsApp Business (Cloud API)

Connect a WhatsApp Business number through Meta's Cloud API so customers who message it are answered by your governed flow. Channel key: whatsapp.

What you need

  • A Meta developer account and a Meta app with the WhatsApp product added (https://developers.facebook.com/apps).
  • A WhatsApp Business Account (WABA) with a phone number (the dashboard gives you a test number to start with).
  • From the App Dashboard: the Phone number ID, a permanent access token (System User), and the App secret.
  • Business verification + display-name approval before messaging real customers at scale (test numbers work without it, for up to 5 recipients).

Official documentation

Set up on Meta

  1. Create the app: developers.facebook.com → My Apps → Create App → use case Other → type Business → add the WhatsApp product.
  2. API Setup (WhatsApp → API Setup): note the Phone number ID (not the display number) and the WhatsApp Business Account ID. Add your own phone as a test recipient and send the "hello_world" template to confirm the number works.
  3. Permanent token: Meta Business Suite → Business settings → Users → System users → Add (Admin) → Assign assets: your app (full control) and the WABA → Generate new token with whatsapp_business_messaging and whatsapp_business_management. Temporary dashboard tokens expire after 24 h.
  4. App secret: App Dashboard → App settings → Basic → App secret → Show.
  5. Webhook: WhatsApp → Configuration → Webhook → Edit: paste the Callback URL and Verify token shown by Tools Anatomy after you connect (step below), click Verify and save, then Manage → subscribe the messages field.
  6. Go live: complete Business verification and register a real number (WhatsApp → Add phone number), then switch the app to Live mode.

Connect in Tools Anatomy

  1. /channels → Messaging channels → WhatsApp Business → Connect.
  2. Fill in: Phone number ID, Access token (permanent), App secret. Verify token (advanced) can be left empty — one is generated.
  3. Connect validates the token against the phone number (GET /{phone_number_id}) and shows the Callback URL and Verify token to paste into the Meta webhook configuration (step 5 above). The GET handshake echoes hub.challenge only when the verify token matches.
  4. Every POST from Meta must carry a valid X-Hub-Signature-256 (HMAC-SHA256 of the raw body with the App secret); others get 401.

Secrets (access token, app secret) live in the Secret Manager and are never shown again.

Identity we derive

Canonical key Source Notes
external_user_id messages[].from (wa_id, digits) stable phone-based id
channel whatsapp
phone_number + + wa_id (E.164) runtime_only
display_name contacts[].profile.name user-controlled, runtime_only
email —

conversation_context.channel_account_id = the receiving phone number ID (so one flow can serve several numbers). Thread = the customer's wa_id.

Limits

  • 24-hour customer service window: free-form text replies are only delivered within 24 h of the customer's last message. Outside it WhatsApp requires an approved message template — the channel does not send templates, so a late reply fails with a platform error (visible in the thread status).
  • Text is split at 4096 characters (text.body limit).
  • Media (image, audio, document, video, sticker, location, contacts, interactive replies) arrives as an attachment; the flow answers text-only.
  • Delivery/read statuses webhooks are acknowledged and ignored.
  • Rate limits and per-number messaging tiers apply (see Meta docs).
  • Meta retries undelivered webhooks for up to 36 h; events are deduplicated on the WhatsApp message id (wamid…).

Test it

With the app in development mode, message the test number from a phone you added as a recipient. The webhook delivery log in the App Dashboard (Webhooks → Test / Recent deliveries) shows Meta's view.

Troubleshooting

  • Verify token mismatch in the Meta dashboard — the URL or the token was pasted incorrectly; copy both again from the channel drawer.
  • "platform rejected the credentials" — expired temporary token, or the System User is not assigned to the app/WABA.
  • Replies fail with (#131047) / re-engagement — the 24-hour window has closed; the customer must message again.
  • (#131030) Recipient not in allowed list — test numbers can only message recipients added in API Setup.