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 会将大约 6 个月的历史记录同步到 API，因此软件能获得上下文，而不是从空白开始。
我可以撤销吗？
可以。您可以断开号码，应用会继续像以前一样运行。连接本身不会永久改变号码。
这和非官方 WhatsApp API 一样吗？
不一样，这是不同产品。Coexistence 是 Cloud API 上的 Meta 官方功能；非官方网关通过已连接设备驱动 WhatsApp Web，会违反条款并导致号码被封禁。其费用不包含在 EasyCoexistence 订阅中，需向各提供商另行支付。
准备开始了吗？
几分钟即可设置 WhatsApp Coexistence，而不是几个月。应用会继续在手机上运行。
Start Free Trial7 days free. Nothing is charged until the trial ends.