Skip to main content

WhatsApp Cloud API

The platform integrates with Meta's WhatsApp Cloud API to send and receive WhatsApp messages — broadcast templates, conversation flows, support replies. The integration includes an anti-ban bundle that monitors account health and classifies errors so a single bad campaign doesn't get your number restricted.

When to use it​

  • Any WhatsApp messaging volume above a small pilot (Meta requires Business API for marketing at scale).
  • You want first-class observability — quality rating, messaging-tier limits, account-review status — directly in the admin.
  • You're running cashback or loyalty flows that must be auditable per delivery.

How it works​

You connect a WhatsApp channel (a phone number registered in Meta Business Manager) to the platform. Inbound messages arrive via Meta's webhook to a URL the platform exposes; outbound messages go through the MetaWhatsAppProvider.

The inbound webhook URL pattern is:

https://{your-host}/api/whatsapp-webhook/{channelId}

Each channel has its own URL; Meta needs both the URL and a verify token (you set both when you configure the channel).

The anti-ban bundle​

WhatsApp can ban accounts (or push them into the lowest messaging tier) when they send too many messages too fast, too many low-quality templates, or messages to opted-out recipients. The anti-ban bundle is two cooperating pieces:

Account-health monitor​

A background worker periodically calls Meta's per-phone health API for each active channel and stores a snapshot:

  • Quality rating (Green / Yellow / Red).
  • Messaging-limit tier (250 / 1k / 10k / 100k / unlimited).
  • Phone status, name status, account-review status.

Snapshots are written every sweep so you can see the trajectory. A [META-HEALTH-DEGRADED] notification is fired the moment a snapshot worsens compared to the previous one — so you find out within minutes, not after the campaign tanks.

Send-time error classifier​

Every send goes through an error classifier that maps Meta's numeric error codes to one of:

OutcomeWhat the platform does
TransientRetryRate-limit or throughput limit. The platform retries with backoff.
AccountRestrictedMeta has restricted the account or phone. The platform stops sending and alerts. Keep sending and you'll get banned.
TemplateDisabledThe template was paused, disabled, or quality-flagged. The platform marks the template unusable until you fix it.
RecipientBlockedThe recipient opted out or blocked you. The platform won't re-attempt this recipient.
InvalidRequestBad payload (unknown 4xx). The platform marks the row failed and surfaces the error in the admin.
UnknownAnything else. The platform logs and treats it as transient.

This means a bad campaign doesn't snowball — once the platform sees an AccountRestricted signal, it backs off automatically.

Step-by-step​

Provision a channel​

  1. Have a phone number registered in your Meta Business Manager with a verified business.
  2. Get the WhatsApp Business Account ID, phone-number ID, and a permanent access token from Meta.
  3. In the platform, go to Communications → Channels and click Create channel.
  4. Pick WhatsApp as the type and fill in:
    • Phone number (display only).
    • Phone-number ID (from Meta).
    • WABA ID.
    • Access token.
    • Verify token — any string you control; you'll configure Meta with the same value.
  5. Save. The platform shows the webhook URL for this channel.

Configure Meta to send you webhooks​

  1. In Meta Business Manager, open the app for this WhatsApp Business Account.
  2. Add the platform's webhook URL and verify token (Meta will hit the URL once to verify).
  3. Subscribe the app to the messages event.

Submit templates for approval​

WhatsApp marketing templates need Meta approval before they can be sent. In the platform's Templates section, draft the template and submit it to Meta — the platform tracks approval status and disables sending until the template is approved.

The platform supports the standard template categories: Marketing, Utility, Authentication.

Send a broadcast​

  1. Go to Communications → Broadcasts and create a broadcast.
  2. Pick the WhatsApp channel and an approved template.
  3. Pick a segment of members.
  4. Send — the platform paces sends to stay under your messaging-limit tier.

Limits and gotchas​

  • Meta App Review. You can't broadcast templates at scale until your Meta business is fully reviewed. Plan for 2–8 weeks of approval ping-pong before launch. The platform's role is to surface what Meta needs; the conversation is between you and Meta.
  • Quality rating drops fast. Send too many marketing templates to cold contacts and Meta will push you to Yellow within hours. Use the Meta-health page (see Meta health) to watch it.
  • AccountRestricted is a stop signal. Don't paper over it by retrying — fix the cause first (template quality, recipient list, opt-in compliance).
  • Webhook URL is per channel. Misconfiguring it sends inbound messages to the wrong tenant — double-check the channel id in the URL.
  • Inbound media downloads require an extra API round-trip to Meta. Slow networks can hit timeouts; the platform falls back to a placeholder image in that case.