WhatsApp Official connection errors

When a WhatsApp Official connection doesn’t finish, SquadOS shows a notice with a title and the next step. The View documentation button in the notice opens the matching section of this page.

Most errors are fixed by selecting Connect with WhatsApp again and making a different choice in the Meta window. Account changes, such as deleting a pending number, are made in Meta’s WhatsApp Manager, at business.facebook.com.

The Meta authorization expired

The code Meta returns at the end of the window is valid for a few seconds and can be used only once. It expires when the window sits idle or when the same attempt is sent again.

Select Connect with WhatsApp again and finish the Meta window without pausing. Keep the SquadOS tab open until it shows Connected.

Meta rejected the authorization

Meta did not confirm the access granted in the window. This happens when the Facebook profile you used doesn’t manage the WhatsApp Business account, or when the authorization was revoked.

Select Connect with WhatsApp again.
In the Meta window, sign in with the Facebook profile that manages the business portfolio and the WhatsApp Business account.
Finish every screen and approve the access SquadOS requests.

WhatsApp permissions are missing

SquadOS needs two permissions: manage the WhatsApp Business account and send messages. If either one is cleared in the Meta window, the connection is rejected.

Connect again and keep both permissions selected on the access screen.

No WhatsApp Business account was shared

The Meta window was closed before the step where you choose or create the WhatsApp Business account.

Connect again and go through every screen until you choose or create the account and the number. Closing the window halfway doesn’t create the connection.

More than one WhatsApp Business account was shared

Several accounts were selected in the Meta window, and SquadOS can’t tell which one to use.

Connect again and, in the Meta window, select only the account and number for this inbox. To connect another number, create another inbox.

SquadOS did not receive access to the WhatsApp Business account

The chosen account wasn’t included in the access granted to SquadOS, or the profile you used isn’t allowed to share it.

Confirm in WhatsApp Manager that your profile is an admin of the account.
Select Connect with WhatsApp again.
On the Meta access screen, select the WhatsApp Business account you want to connect.

The WhatsApp Business account has no number

The shared account doesn’t have a phone number yet.

Add the number to the account in WhatsApp Manager, under Phone numbers, and connect again. With Coexistence, the Meta window adds the WhatsApp Business app number for you.

The number is not in the chosen account

The Meta window returned a number that doesn’t belong to the chosen account. This usually happens when earlier attempts left the same number pending in more than one account.

Open WhatsApp Manager and review the accounts in your business portfolio.
If the number shows as Pending or Not verified in an account you don’t use, delete that entry. Meta asks for your account password to confirm.
Select Connect with WhatsApp again and choose the account the number should belong to.

SquadOS did not receive access to the number

The account was shared, but the chosen number was left out of the access granted.

Connect again and, in the Meta window, select the number you want to use in this inbox.

This inbox uses another number

While reconnecting, the Meta window returned a number or account different from the ones this inbox already uses. SquadOS rejects the change so it doesn’t mix the conversations of two numbers.

To reconnect, choose the same number and account as this inbox in the Meta window.
To use another number, connect a new inbox.

The number needs another connection mode

The chosen mode doesn’t match the number.

If the number is on the WhatsApp Business app on your phone, choose Coexistence.
If the number isn’t on the app, choose Official API only.
When reconnecting, use the same mode the inbox was created with.

This number is not on the WhatsApp Business app

Coexistence only works with a number that is active on the WhatsApp Business app on your phone. The regular WhatsApp app doesn’t work.

On your phone, confirm the number is on the WhatsApp Business app, on the latest version.
Select Connect with WhatsApp again.
In the Meta window, choose to connect the existing WhatsApp Business app account and follow the instructions shown on your phone.

For a number that isn’t on the app, choose Official API only.

Meta did not turn on message delivery

The connection was authorized, but Meta didn’t turn on delivery of incoming messages to SquadOS.

Connect again. If the error continues, check in WhatsApp Manager that the account is active and has no restrictions, and resolve any notices Meta shows there.

Meta did not register the number

In Official API only mode, the number must be registered with Meta’s API, and the registration was rejected.

Check in WhatsApp Manager that the number is active and isn’t used by another API service.
If the number uses two-step verification, follow Two-step verification.
To keep using the WhatsApp Business app on your phone, connect with Coexistence mode.

The WhatsApp connection is unavailable right now

The error is on the SquadOS side, not in your account. Support is notified automatically.

Try again later. Nothing needs to change in Meta.

Couldn’t connect WhatsApp

The connection was rejected for a reason that doesn’t have its own guidance yet. The notice shows a code, for example invalid_connection_mode.

Try again. If the error continues, contact SquadOS support and share the code shown in the notice.