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. | Paste one in Settings → Connections → Cloud credentials |
The commonest cause of expired on the manual path 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.
If you connected with Facebook, there is no token for you to replace. Use Reconnect with Facebook instead (see Access removed).
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.
The IDs don't match
Before a connection is saved, the app checks the IDs with Meta. The setup wizard, the Change button on a connection card, and Cloud credentials can all show these messages:
| Message says | What happened | Fix |
|---|---|---|
| "…is the same as the WhatsApp Business Account ID" or "This is the WhatsApp Business Account ID, not a Phone Number ID" | The WABA ID was entered in the Phone Number ID field too. | Click Find numbers and pick your number instead of typing the ID |
| "Phone number ID … is not on WhatsApp Business Account …" | The number belongs to a different WABA, or the ID was mistyped. | Pick from the list. If your number is not in it, the WABA ID is the wrong one: correct it in Cloud credentials first |
| "Meta does not recognise … as a WhatsApp Business Account this token can access" | The WABA ID is wrong, or the system user was never assigned that WABA. | Check the WABA ID, then assign the WABA to the system user |
| "Phone number ID … is +1 555…, not +260…" | The display number you typed is a different number from the one you picked. | Pick the number from the list; the display number fills itself in |
| "Meta rejected the Graph API token as invalid or expired" | The token is wrong, revoked or expired. | Generate a new system-user token (see Token status above) |
The same mix-up happens between the WABA ID and the Business ID. The app wants the WABA ID.
A connection uses the wrong number
If messages go out from the wrong number, or the WhatsApp profile won't load, click Change next to the phone number on the connection's card and pick the right number. The card shows the number and its Phone Number ID, so you can see what is set. If a card says No phone number selected, click Choose number.
If you just changed the WABA ID in Cloud credentials, the app warns you about every connection whose number is not on the new account. Fix each one with Change.
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
Every connection card has an Incoming messages line. It shows whether Meta actually sends that number's messages to The Rook:
| Badge | Meaning | Section |
|---|---|---|
| Receiving messages | Working. The line underneath shows when the last message arrived. | — |
| Not receiving messages | Meta isn't sending this number's messages here yet. | Not receiving |
| Token can't connect webhooks | Your token belongs to a different Meta app. | Token from the wrong app |
| Messages go elsewhere | Another URL receives this number's messages. | Messages go elsewhere |
| Status unknown | The check itself failed. The line underneath says why. | Status unknown |
Team owners and admins see a Fix steps panel under any badge that isn't green. Other members see the badge only: ask a workspace owner or admin to fix it.
Not receiving messages
Meta isn't sending this number's messages to The Rook yet. Normally this is set up for you when the connection is created, but it can be undone in Meta, or it fails when the token lacks permissions at that moment.
Subscribe
Open Fix steps on the connection card and click Subscribe.
Send a test message
The card shows Waiting for first message. Send a WhatsApp message to the number from any phone.
Watch it turn green
The card turns to Receiving messages on its own as soon as the message arrives. If nothing arrives within 10 minutes, the card says Still nothing? Check the token status, then contact the platform operator.
Token from the wrong Meta app
A system-user token is generated for one Meta app. If yours was generated for a different app (for example one you built yourself), Meta lets it send messages but refuses to route your number's messages to The Rook's app.
- In Business Settings, open System users and select your system user.
- Click Add assets → Apps and assign The Rook's app (the card names it) with Manage app.
- Click Generate new token, choose that app, and tick both
whatsapp_business_messagingandwhatsapp_business_management. - Paste the new token in Settings → Connections → Cloud credentials, then click Check again on the card.
See System-user access token for the full walk-through.
Messages go elsewhere
Meta lets a WhatsApp Business Account, or a single number on it, override where its messages are delivered. When an override points at another URL, that URL gets your messages instead of The Rook. The card shows the URL, and whether the override is on the whole account or only this number.
This usually means the number was connected to another product or test setup before. Only the platform operator can switch it back with Send messages here instead, because whatever uses that other URL stops receiving messages. Contact them with the connection name.
Status unknown
The check couldn't reach a verdict. The reason is under the badge:
| Message | Fix |
|---|---|
| "Your token has expired or was revoked." | Generate a new token and paste it in Cloud credentials (Token status) |
"The token is missing the whatsapp_business_management permission." | Generate a new token with that permission ticked, and paste it in Cloud credentials |
| "Meta doesn't recognise the WABA ID." | Correct the WABA ID in Cloud credentials |
| "Couldn't reach Meta. Nothing was changed." | Click Try again in a minute |
If the badge says Status unknown with a note that the server can't check incoming messages yet, the platform is running an older version. Messages may still arrive normally.
If none of this helps, contact the platform operator. Mention whether your own replies still send. If they do, but nothing comes back in, the platform's webhook is usually rejecting Meta's deliveries, which the operator can see straight away in their Webhook setup panel.
Messages for a number no connection uses (operators)
Platform admins see an amber banner in Settings → Connections → Webhook setup when Meta delivers messages for a phone number ID that no connection uses. Those messages arrive and are dropped.
- Click Which team? to find the WhatsApp Business Account the number is on, and the team that owns it, where a stored token can see it.
- Then use Change on the right connection's card to pick that number, or create a connection for it.
- Copy ID copies the phone number ID, for pasting into the connection.
The banner disappears once a connection uses the number.
Connect with Facebook
These are the messages the Connect with Facebook path can show.
| What you see | What happened | Fix |
|---|---|---|
| Nothing happens when you click Connect with Facebook | The browser blocked the Meta pop-up. | Allow pop-ups for this site (usually an icon at the end of the address bar), then click again |
| "You closed the Facebook window before finishing" | The Meta window was closed part-way. The wizard says which step you reached. | Click Connect with Facebook again. Anything you already created in Meta is kept, so pick it instead of creating it twice |
| "The Facebook session expired" | Meta's sign-in code is only valid for about 30 seconds after the window closes, and it ran out before it reached us (often a slow connection). | Try again. Nothing was saved, so it is safe to repeat |
| "Facebook reported an error" with a session ID | Meta's own flow failed. | Try again. If it repeats, send us the session ID shown. It lets Meta trace the attempt |
| "That PIN is incorrect" | The number already has a two-step verification PIN, and the one entered doesn't match. | Enter the existing PIN. If nobody knows it, the owner can reset it in WhatsApp Manager → Phone numbers → the number → Two-step verification |
| "Too many registration attempts" (error 133016) | Meta allows 10 registration attempts per number in any 72 hours. | Wait out the 72 hours from the first attempt, then try once with the correct PIN. Attempts during the lockout fail |
| "This access was granted to a different app" | The Meta window was completed for another provider's app, not this platform's. | Start again from this app's wizard so the access is granted to us |
| "Connecting a number that stays on the WhatsApp Business app isn't supported yet" | You chose to connect your existing WhatsApp Business app account. | Move the number to the Cloud API first (migrating a number), then connect again |
| No number to pick after the window closes | You finished in Meta without adding a phone number. | Add a number to the WhatsApp Business Account in WhatsApp Manager, then click Find numbers, or run Connect with Facebook again and add it there |
Access removed
If someone removes this platform's access in Meta's Business Settings, Meta tells us and a banner appears across the top of the app. Messaging stops until you reconnect: open Settings → Connections → Cloud credentials and click Reconnect with Facebook, choosing the same business portfolio and WhatsApp Business Account. Connections, conversations and contacts are kept.
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.