WhatsApp via Meta Cloud API
Connect WhatsApp with your own Meta app — a permanent system-user token, the four fields to paste, and the messages webhook.
Two ways to connect WhatsApp, and this is one of them. The Meta Cloud API route uses your own Meta app: no per-message provider fee, and the app's name and branding are yours. The alternative is Twilio, which shares one credential set with SMS and voice — see WhatsApp via Twilio. Follow one page or the other, not both.
What you need
A Meta developer app of type Business, with the WhatsApp product added and a phone number registered under it (WhatsApp → API Setup).
1. Generate a permanent token
The token on the API Setup page expires in 24 hours — fine for a first test, wrong for production. Create a permanent one:
- 1In
business.facebook.com→ Users → System users, create a system user. - 2Assign your app to it with full control.
- 3Generate token with the
whatsapp_business_messagingandwhatsapp_business_managementpermissions, expiry Never.
2. Connect the channel
Add a WhatsApp channel with the Meta Cloud API provider and four values:
| Field | Where it comes from |
|---|---|
| Meta App Secret | App → Settings → Basic |
| Verify token | Any string you choose — you will paste the same one into Meta |
| Permanent access token | The system-user token from step 1 |
| Phone number ID | WhatsApp → API Setup — the numeric id under the number, not the number itself |
Copy the webhook URL shown after connecting. Credentials are stored encrypted.
3. Point Meta at the webhook
In the Meta app: WhatsApp → Configuration → paste the webhook URL as the Callback URL, with the same verify token. The handshake is answered automatically. Then subscribe the webhook to the `messages` field.
Delivery and read statuses events arriving on the same webhook are ignored.
Verify it works
Message the WhatsApp number. The conversation should appear in the Inbox tagged WhatsApp, and the AI should reply.
Inbound requests are verified with x-hub-signature-256 against your app secret.
The 24-hour window
Free-form replies must land inside WhatsApp's 24-hour customer-service window, which resets on each customer message. Outside it the send is refused and the message is marked Not delivered with that reason. evoriqa does not send re-engagement templates.
Media
Inbound media arrives as a Meta media id, resolved at ingest into a short-lived CDN link — download anything you need to keep. If a link cannot be resolved, the message still arrives with an attachment placeholder.
Troubleshooting
| Symptom | Cause |
|---|---|
| The URL couldn't be validated | The callback is not publicly reachable over HTTPS, or the verify token is not byte-identical |
| No messages yet after verifying | The webhook is not subscribed to the messages field |
| Signature rejected | Meta is delivering; the app secret on the channel is wrong |
| Sends stop working after a day | You used the 24-hour API Setup token instead of a permanent one |
| Not delivered, window reason | Outside the 24-hour window |
Where to go next
Last updated