Meta update: coexistence clients who switch devices now reconnect automatically. No action needed from you or them.
Another coexistence update from Meta, and this one is genuinely nice. They published a new guide called "Reconnect offboarded coexistence clients" and it covers a pain point a lot of us have hit.
The old problem
When a coexistence client switched phones, reinstalled their WhatsApp Business app, or re-registered their number, their Cloud API companion got offboarded. Getting them back on meant manual intervention. Clients had to go through onboarding again, you had to handle it on your end, and the whole thing was more friction than it needed to be.
What changed
Reonboarding is now automatic. Here's the full flow:
- Client switches devices, reinstalls, or re-registers
- Cloud API companion is offboarded. You get an ACCOUNT_OFFBOARDED webhook
- During the WA Business app registration flow, client sees a pre-checked opt-in listing all their previously connected Cloud API products
- If they don't opt out, reonboarding runs in the background automatically
- Within a few minutes, you get an ACCOUNT_RECONNECTED webhook and Cloud API messaging resumes
Nothing required from you or the client beyond them completing registration.
Two new webhooks to handle
ACCOUNT_OFFBOARDED fires when the companion gets offboarded due to device change or re-registration:
{
"entry": [{
"id": "<WABA_ID>",
"changes": [{
"value": {
"event": "ACCOUNT_OFFBOARDED"
},
"field": "account_update"
}]
}],
"object": "whatsapp_business_account"
}
ACCOUNT_RECONNECTED fires once reonboarding completes:
{
"entry": [{
"id": "<WABA_ID>",
"changes": [{
"value": {
"event": "ACCOUNT_RECONNECTED"
},
"field": "account_update"
}]
}],
"object": "whatsapp_business_account"
}
What to do when you get ACCOUNT_OFFBOARDED
Pause any pending Cloud API message sends for that client. Messages will fail while reonboarding is in progress. Then just wait for ACCOUNT_RECONNECTED before resuming.
What stays up during reonboarding
Your partner access to the WABA stays intact and webhook subscriptions keep firing. Cloud API messaging is suspended during the window, but since reonboarding typically finishes within a few minutes the gap is minimal.
A few things to note
Only the Cloud API companion is restored automatically. If your client used WhatsApp Web or other companion devices, they have to re-link those manually. Also, if a different partner or coexistence product onboards the WABA during the reconnection window, eligibility for reonboarding is cleared.
The prerequisite is that your app needs to be subscribed to the account_update webhook field. If you already handled the PARTNER_REMOVED changes from last week, you're already in the right place.