Changing the phone number on a Coexistence connection
A Coexistence connection belongs to one phone number. When the business changes its number in the WhatsApp Business app, Meta disconnects the connection with the reason CHANGE_NUMBER. The new number is a separate business phone number on the platform, and it has to be onboarded through the Coexistence flow as a new connection.
The disconnection reason Meta reports when the business changed its phone number.
Initial cap on registered business phone numbers for a new business portfolio, raised to 20 later.
A number used to send paid messages within this period cannot be deleted from the platform.
What happens to the connection when the number changes?
It ends. Meta lists a change of phone number among the reasons a Coexistence connection is disconnected, and reports it in the account_update webhook's disconnection_info with the reason CHANGE_NUMBER.
That is the platform being consistent rather than strict. Everything the API side knows is keyed to a business phone number: its phone number ID, display name, quality rating and webhook subscriptions. A different number is a different asset, so nothing attached to the old one moves across on its own, and the old connection stops working at the moment of the change.
How do I connect the new number?
As a first connection. The new number has to satisfy the same conditions as any number joining Coexistence, and then go through onboarding from the start. Nothing from the old connection is reused, so it helps to treat the switch as a short project with a date.
- It is active in the WhatsApp Business app, on version 2.24.17 or newer.
- It sits in a Business Portfolio you administer.
- It is not attached to another provider.
- Its display name is provided at registration, as for any business phone number.
What should be updated on the API side?
Every place the old number or its ID is stored. Integrations that send through the Cloud API address a phone number ID, so a CRM, an automation workflow or an AI agent still pointing at the old ID will fail rather than switch over.
The new connection also starts its own onboarding questions again, including whether to share chat history and the 24 hour window to synchronise it. A webhook destination set on the old connection has to be applied to the new one. Portfolio capacity is worth checking too: Meta caps a new business portfolio at two registered business phone numbers until it is verified or reaches a 2,000 messaging limit.
What happens to the old number on the platform?
It stays an asset in the WhatsApp Business Account until someone removes it. Meta only lets business portfolio admins delete business phone numbers, and refuses deletion for a number used to send paid messages in the last 30 days.
Deleting is optional housekeeping rather than a requirement for connecting the new number, but leaving stale numbers in the account makes it easy for a system to keep addressing the wrong one. Removing it once the 30 days have passed keeps the account readable.
Common mistakes
- Changing the number in the app before planning the reconnection. The old connection ends at that moment.
- Leaving the old phone number ID in integrations. Sends fail instead of following the new number.
- Trying to delete the old number right after the switch. Meta blocks it if it sent paid messages in 30 days.
EasyCoexistence shows a CHANGE_NUMBER disconnection on the connection timeline as Meta reports it, and the new number connects through the same self-serve Embedded Signup in about two minutes.
Frequently asked questions
Does the connection follow my new number?
No. Meta disconnects it with the reason CHANGE_NUMBER, and the new number is onboarded as a new connection.
Do I need a new phone number ID?
Yes. The new number is a separate business phone number on the platform, with its own ID.
Can I delete the old number immediately?
Only if it has not sent paid messages in the last 30 days, and only a portfolio admin can delete it.
Do I have to choose a display name again?
Yes. Meta requires display name information when a business phone number is registered.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialVerified on