The account_update webhook, and every disconnection reason
account_update is how Meta reports that a connection changed state. Its event field names what happened and, for a removal, disconnection_info.reason names why. That reason is the difference between a number that will come back and one that is gone.
- The authoritative disconnection signal
- Six named reasons, not a generic error
- Reason decides recoverable or final
Nothing charged for 7 days. Cancel anytime.
The event Meta sends when the app is uninstalled from an account.
Named disconnection reasons a removal can carry.
The primary device inactivity window, which arrives as PRIMARY_INACTIVITY.
What events does account_update carry?
PARTNER_REMOVED, when the app is uninstalled from the WhatsApp Business Account. This is the authoritative disconnection signal and the one worth building on, rather than inferring a disconnection from a field going false.
ACCOUNT_OFFBOARDED, when the number is offboarded entirely. ACCOUNT_RECONNECTED, when a previously removed connection comes back. And the enforcement events: ACCOUNT_RESTRICTION and ACCOUNT_VIOLATION, alongside events whose names include DISABLED or BAN.
Verification and approval outcomes also arrive here, with event names containing VERIFIED or APPROVED. A handler should switch on the event name and treat anything unrecognised as informational rather than failing on it, because Meta adds events without notice.
What are the disconnection reasons?
Six, and they mean very different things.
PRIMARY_INACTIVITY is the roughly fourteen day rule: the WhatsApp Business app was not opened on the primary device. Recoverable, and by far the most common.
COMPANION_INACTIVITY is the same idea on a companion device, on a longer window of about thirty days.
BUSINESS_DOWNGRADE means the number moved back to the consumer WhatsApp app, which ends Coexistence because Coexistence requires the Business app.
CHANGE_NUMBER means the phone number itself changed. USER_RE_REGISTERED means it was re-registered on a new device. And ACCOUNT_DISCONNECTED means the client disconnected it deliberately, or enforcement did.
The reason also arrives alongside disconnection_info.initiated_by, which says whether a person or the system did it.
Why does the reason matter more than the event?
Because PARTNER_REMOVED on its own does not tell you whether to act.
A number removed for PRIMARY_INACTIVITY is coming back: the business opens the app, reconnects, and everything resumes. Treating that as a customer who left produces a cancellation email to somebody who is still a customer.
A number removed for BUSINESS_DOWNGRADE or ACCOUNT_DISCONNECTED is a different situation, and treating it as temporary means a connection sitting in limbo forever.
When a removal arrives with no reason at all, initiated_by is the fallback: a removal a person performed reads as deliberate, while an unexplained system one does not. That distinction is worth making in code rather than in a support conversation later.
Common mistakes
- Treating every PARTNER_REMOVED the same. The reason separates a fortnight of quiet from a customer who left.
- Inferring disconnection from a field going false rather than from this event. That is what produces false alarms.
- Failing on an unrecognised event name. Meta adds events and a handler should skip what it does not know.
EasyCoexistence handles every one of these by name, records the reason on the connection timeline, and separates a recoverable inactivity removal from a number that is actually gone.
Frequently asked questions
Is PARTNER_REMOVED permanent?
Usually not. Most arrive with PRIMARY_INACTIVITY, which means the app went unopened and reconnecting restores everything.
Does reconnecting restore my webhook destination?
No, and this is the trap. The destination is an override on the app subscription and is uninstalled with it. It has to be reapplied.
What is COMPANION_INACTIVITY?
The same inactivity idea on a companion device rather than the primary one, on a longer window of around thirty days.
Can I get this event without a reason?
Yes. When that happens, disconnection_info.initiated_by is the only signal for whether it was deliberate.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialNothing charged for 7 days. Cancel anytime.Verified on