Connection troubleshooting
Every error the setup wizard and the inbox can show you, and what actually fixes it.
Work down this page in order — the causes are roughly ordered by how often they are the real problem.
Token status is invalid or expired
The app checks your token's health and shows a banner across the top of the dashboard when something is wrong. What each state means:
| Status | Meaning | Fix |
|---|---|---|
| Valid | Working. | — |
| Expiring soon | A dated token is nearly up. | Rotate it before it dies |
| Expired | The token's lifetime ended. | Generate a new Never-expiring token |
| Invalid | Meta rejected it. | Usually revoked, or the wrong token was pasted |
| Missing | No token stored. | Re-run the setup wizard |
The commonest cause of expired is having pasted the temporary token from Meta's API Setup page, which lasts 24 hours. You need a system-user token with expiry set to Never.
Permissions error, though the token looks right
Almost always the system user is missing an asset assignment. Both are required:
- Business Settings → Users → System users → your user → Add assets → Apps — your app, with Manage app.
- Add assets → WhatsApp accounts — your WABA, with Full control.
Check the permissions too: whatsapp_business_messaging and
whatsapp_business_management must both be ticked. See
System-user access token.
Wrong Phone Number ID
If verification fails or messages go nowhere, confirm you pasted the Phone
number ID and not the phone number itself. It is a ~15 digit value on the
API Setup page under "Send and receive messages" — not +260 97….
The same confusion happens between WABA ID and Business ID. The app wants the WABA ID.
Sending is blocked with EMAIL_NOT_VERIFIED
You have not confirmed your email address yet. Outbound sending stays locked until you do. Use the Resend email link in the amber banner at the top of the app. See Create your account.
Number not registered
Meta reports the number is not registered on the Cloud API. Either the verification code step was never completed, or the number is still attached to the WhatsApp app. See migrating a number.
Messages send but never arrive
Check the 24-hour window
Free-form messages to someone who has not written in the last 24 hours are rejected. Use a template. See the service window.
Check your messaging limit
A restricted number cannot start new conversations until the window resets. WhatsApp Manager → Overview shows your tier and any warnings.
Check the recipient has not blocked you
A message that stays on "sent" and never delivers usually points at the recipient side.
Check the failure reason on the message
Failed sends record Meta's error against the message in the inbox, which names the actual cause.
Inbound messages do not appear
You do not configure a webhook — that is a one-time platform-level task done by the operator, not per customer. If nothing arrives at all:
- Confirm the connection shows a valid token.
- Confirm you messaged the right number.
- Contact the platform operator: inbound delivery is a platform-side subscription, and if it is misconfigured no customer receives anything.
Templates will not send
- Only approved templates can be sent; pending and rejected ones are hidden.
- The template must belong to the same connection you are sending from.
- Variable counts must match what the template declares.
- Templates require the Templates feature on your plan.
See Message templates.
Still stuck
Send us the details — the connection name, what you were doing, and the exact error text. That is usually enough for us to pinpoint it.