The WhatsApp Cloud API is Meta’s own hosted version of the WhatsApp Business Platform. Connect it directly to Outbound OS using your Meta app, a system-user access token and your registered number’s identifiers. Configure the incoming webhook separately so customer replies and delivery events reach your CRM.

You need a Meta business portfolio, a number eligible for your chosen Cloud API setup or migration route, and your Outbound OS instance on a public HTTPS address — see Install → HTTPS.

1. Create a Meta app with WhatsApp

Go to developers.facebook.com/apps and create an app with the WhatsApp use case, linked to the business portfolio that owns your messaging account.
Add the WhatsApp product to the app.
Under WhatsApp → API Setup, add your business phone number and verify it. Copy its Phone number ID and WhatsApp Business Account ID. The Phone number ID is not the phone number itself.

2. Generate a system-user access token

A temporary API Setup token is unsuitable for a lasting server connection. Create a dedicated system-user token and select a duration Meta makes available for your account:

In Meta Business Settings → Users → System users, add a system user for this integration.
Grant access to the app and WhatsApp account the integration needs.
Generate a token for the app with the whatsapp_business_messaging and whatsapp_business_management permissions. Record its expiry and renewal requirements for your installation.

Treat the token like a password. Outbound OS stores it encrypted.

3. Connect the number in Outbound OS

Open Integrations → WhatsApp, add a number and choose Meta Cloud API as its provider.
Enter the Phone number ID, WhatsApp Business Account ID and access token.
Press Test connection. It reads the number’s verified name and quality rating from Meta. This confirms credential access, not end-to-end delivery. Verify incoming and outgoing messages using a number you own before customer outreach.

4. Receive replies and receipts

Add two values to .env and apply them:

.env

META_APP_SECRET=<App secret from App settings → Basic>
META_WEBHOOK_VERIFY_TOKEN=<any long random string>

Terminal

docker compose up -d

Then, in your Meta app, open WhatsApp → Configuration → Webhook:

Callback URL: https://your-host/webhook/meta
Verify token: the same random string as in .env.
Press Verify and save, then subscribe to the messages field.

Every delivery is checked against META_APP_SECRET; one with a wrong signature is rejected. After verifying the subscription, send an incoming message from a number you own and confirm it appears in the inbox. Message states update from the delivery and read receipts Meta reports; provider acceptance is not proof of delivery.

5. Set a first-contact template

WhatsApp only lets a business start a conversation with a template Meta has approved. Create one in WhatsApp Manager → Message templates, using {{1}} for the lead’s first name and {{2}} for their country:

Example template body

Hi {{1}}, thanks for your enquiry. We ship to {{2}} — could you share the quantity you need so we can send pricing?

Once it is approved, select it as the number’s first-contact template in Integrations → WhatsApp, with its language code (for example en or en_US). Eligible leads from enabled live sources can enter the configured outreach flow when the sender is ready and limits permit. Importing a list does not send it.

How the 24-hour window works

When	What you can send
Within 24 hours of the customer’s last message to that sending number	A free-text reply from the inbox, subject to account and provider rules
First contact, or more than 24 hours since they wrote	An approved template only

Messaging charges depend on category, destination and the applicable service-window rules. Configure billing on your WhatsApp Business account before billable campaigns, and check Meta’s current pricing for current rates, free-message rules and payment requirements.

Troubleshooting

Test connection fails with an authentication error

The token has expired or lacks permissions. Generate a System User token as in step 2 — the temporary token from API Setup will stop working.

Meta will not verify the webhook

The verify token must match META_WEBHOOK_VERIFY_TOKEN exactly, the app must have been restarted after setting it, and the address must be reachable over HTTPS from the internet.

Messages send but replies never arrive

Check the webhook is subscribed to messages, and that META_APP_SECRET is the secret of the same app. The app log shows rejected deliveries.

First contact is skipped

Check the recorded skip reason, lead consent and state, enabled outreach settings, sender readiness and limits. Configure an approved first-contact template in Integrations → WhatsApp, or set WA_FIRST_TOUCH_TEMPLATE as a default. Imported, paused, opted-out or otherwise ineligible records should not receive automatic first contact.

Connect the WhatsApp Cloud API