One number.The app and the API, at the same time.
Coexistence is Meta's official mode for running the WhatsApp Business app and the Cloud API on one number at once. The team keeps answering from the phone, with the same chats and the same history, while software sends and receives on that same line.
The choice that used to exist, and no longer does
Coexistence is not a new API. It is the removal of a fork in the road that stopped almost every small business automating anything.
The team answers from the phone. Nothing can be automated, wired or measured.
No APISoftware can reach the number. The Business app stops working on it and the team moves tools.
No appMeta connects the Cloud API to a number the WhatsApp Business app is still using. Both surfaces are live on the same line, and each sees what the other sends.
Who runs a number this way
Two groups, wanting opposite things from the same feature, which is why the connection matters more than any dashboard on top of it.
A small team, a number printed on a van or a storefront, and evenings spent answering the same four questions. They are not replacing anyone. They want confirmations, reminders and the first reply after hours to happen without a human, while the phone still works for everything else.
Many clients, each with a number nobody is allowed to migrate or touch. They need those numbers reachable by the systems they build, and they need to add the next one without a sales call. Coexistence is the only official route onto a number a client's staff still answers by hand.
How a number ends up on both, and where the message events go
Four steps. The only one that touches the phone is a scan, and the one that decides your architecture is the first.
Have the endpoint ready before onboarding starts
Meta verifies a destination before it will deliver to it. It calls your URL with a GET carrying hub.mode=subscribe, your hub.verify_token and a hub.challenge, and your endpoint has to echo the raw challenge back.
The destination must be HTTPS, and a verify token is mandatory. We validate both before the call is made, so a malformed URL fails at our door rather than looking connected and delivering nothing.
Nothing is connected yet. This decides where messages will land. Provider in the pathStored on their serversTheir platformReceives and stores messagesYouA copy, on their scheduleEasyCoexistenceConfig onlyYour endpointNot yet verifiedUsWe set the route, we are not on itRun Meta's Embedded Signup and scan in the app
Meta's own popup opens. You pick the Business Portfolio, the WhatsApp Business Account and the number already registered in the WhatsApp Business app, then approve the connection on the phone by scanning a code.
This is also where you choose whether to share existing chat history. It is a one time onboarding decision and cannot be changed later. The Business app keeps working the moment the scan completes.
The second surface appears. The first one is not removed. After a migrationOne surfaceCloud API onlyBusiness app dead on this numberAfter CoexistenceTwo surfacesWhatsApp Business appSame chats and historyCloud APIOn the same linePoint the message events at your own system
Meta lets an app override where a given WhatsApp Business Account's webhooks are delivered. We set that override to your URL, which moves the two message path fields, messages and smb_message_echoes, straight from Meta to you.
We keep the operational fields, because those are what monitoring is made of: account_update, phone_number_quality_update, account_alerts, account_review_update, business_capability_update and phone_number_name_update. So the dashboard stays useful while conversation content never touches us.
Which events go where once the override is active. Operational eventsDelivered to usMessage pathDelivered to youmessagesEverything a customer sendssmb_message_echoesWhat the team sends from the appYour serverDirectly, never through usKeep it alive, and survive a reconnection
Meta disconnects a Coexistence number after roughly fourteen days without activity on the primary device. That disconnection is reconnectable, and we record it as its own state rather than treating it as a customer leaving.
The part that catches people is what a disconnection does to the route. Meta stores the destination as an override on our app's subscription to the account, so a PARTNER_REMOVED uninstalls the app and takes the override with it. Reconnecting restores sending and monitoring, but not your destination. We put it back automatically, because the first number that hit this rule reconnected fine and silently stopped delivering to the customer's server.
What a reconnection restores by itself, and what has to be put back. Restored by MetaAutomaticSendingThe Cloud API works againOperational eventsMonitoring resumesLost with the appHas to be reappliedYour webhook overrideUninstalled with the appMessage delivery to youSilently stopsWe reapply itOn every reconnection
Why teams run a number this way
- Keep the number that is already printed on vans, receipts and a website, and the mobile workflow around it.
- Add API sending, webhook processing and templates without moving anyone into a new tool.
- Keep message traffic out of a provider's shared inbox, so conversations are not sitting on somebody else's platform.
- Give an agency a way to hold many clients' numbers on one account, each connected in the client's own Business Portfolio.
Eligibility and practical limits
- The number must already be active in the WhatsApp Business app. A number on the consumer WhatsApp app has to be moved there first.
- Sharing existing chat history is a one time choice made during onboarding and cannot be changed afterwards.
- Group chats are excluded from the API on Coexistence numbers, on every provider.
- The primary device needs periodic activity. Meta disconnects the connection after roughly fourteen days without it.
- Meta verification and badge paths differ for Coexistence numbers, and regional availability changes with Meta policy.
What we route to you, and what we keep
Meta lets an app override where a WhatsApp Business Account delivers its webhooks. We set that override to your URL, which splits the events in two.
messagesEverything a customer sends to the numbersmb_message_echoesWhat your team sends from the WhatsApp Business app
account_updateConnection state: removed, offboarded, reconnected, restrictedphone_number_quality_updateQuality rating and throughput changesaccount_alertsAlerts Meta raises against the accountaccount_review_updateOutcomes of a Meta reviewbusiness_capability_updateMessaging limit and capability changesphone_number_name_updateDisplay name approvals and rejections
If a number has no override set, its message events fall back to our default callback, where the handler drops them without persisting. That is enforced in code rather than promised in a policy: there is no storage path for conversation content to take.
The fourteen day rule, and the thing it breaks that nobody mentions
Meta disconnects a Coexistence connection after roughly fourteen days without activity on the primary device. It is reconnectable, so we store it as its own state rather than counting it as a customer who left.
The consequence that costs people is downstream. Your message destination is not a setting on the number, it is an override on our app's subscription to the WhatsApp Business Account. A disconnection uninstalls the app, and the override goes with it. Reconnect and sending works, monitoring works, and messages stop arriving at your server with nothing reporting an error.
We reapply the override on every reconnection. That behaviour exists because it happened: a number hit this rule, reconnected cleanly, and silently stopped delivering.
A failed handshake at that moment, because your server was down or the token changed, is recorded on the connection timeline and the destination is kept rather than discarded, so saving it again is enough to fix it.
What breaks quietly, and how we find out
The WhatsApp Business app keeps working through almost every failure below, which is why nobody notices. These are the ones we check for, and how.
Detected from Meta's account_update webhook, specifically PARTNER_REMOVED, rather than inferred from a field going false. We deliberately do not read is_on_biz_app for this, because it is legitimately false on numbers that are not Coexistence and was causing false disconnections.
Meta's primary device inactivity rule. It is reconnectable, so it is recorded as its own state rather than as a customer who left, and reconnecting restores sending and monitoring.
The destination lives as an override on our app's subscription to the account, so a disconnection uninstalls it. Sending comes back on reconnect and delivery to your server does not. We reapply the override every time, because a number this happened to reconnected cleanly and silently stopped delivering.
We hold the client token and our own System User token against the same account. When one is rejected the other reads the account and settles which of the two actually broke, so a revoked token no longer looks like a lost number.
Polled from Meta on a schedule. A RED rating marks the connection degraded, and quality, messaging tier and throughput level are stored on every check so a decline is visible before it costs a send.
Connecting a number and watching a number are different products. The second one is why this exists.
الوقت المعتاد لربط الرقم، عبر مسح رمز من تطبيق WhatsApp Business.
المدة التي يُبقي فيها رد العميل الجلسة مفتوحة للرد بنص حر.
معدل الإرسال لرقم Coexistence، تحدده Meta ولا يمكن رفعه.
حجم سجل المحادثات الذي تزامنه Meta مع API عند ربط الرقم أول مرة.
الأسئلة الشائعة
هل يجب أن يتوقف فريقي عن استخدام الهاتف؟
لا. هذه هي الفكرة الأساسية من Coexistence. يستمر تطبيق WhatsApp Business في العمل على الرقم نفسه، مع المحادثات نفسها، وتعمل API إلى جانبه.
هل سأفقد محادثاتي الحالية؟
لا. تبقى في التطبيق، وتزامن Meta نحو ستة أشهر من السجل مع API عند ربط الرقم، لذلك يملك البرنامج سياقاً بدلاً من أن يبدأ فارغاً.
هل يمكنني التراجع عنه؟
نعم. يمكن فصل الرقم، ويستمر التطبيق كما كان دائماً. لا يغير ربط الرقم أي شيء فيه بشكل دائم.
هل هذا هو نفسه WhatsApp API غير الرسمي؟
لا، والفرق يحدد ما إذا كان الرقم سيبقى فعالاً. Coexistence ميزة رسمية من Meta على Cloud API. أما البوابات غير الرسمية فتشغّل WhatsApp Web كجهاز مرتبط، ما يخالف الشروط ويؤدي إلى حظر الأرقام.
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
Start Free Trial7 days free. Nothing is charged until the trial ends.