Coexistence: WhatsApp Business App and API on the Same Number

Yes. Meta lets you keep using the WhatsApp Business app on your phone and connect the same number to the Cloud API. Meta's docs call this "onboarding WhatsApp Business app users"; support teams and partners call it Coexistence. You keep chatting one-to-one from the app, your WhatsApp provider (BSP) uses the API to send high volumes, and WhatsApp keeps the message history of both in sync.

You don't need to delete your WhatsApp account or change your number. You connect it through your provider's sign-up flow (Meta's Embedded Signup), and you can choose whether to share your existing chat history.

What you need#

• The WhatsApp Business app, version 2.24.17 or higher. (The regular WhatsApp Messenger app does not qualify; see Move Your Existing WhatsApp Number to the API.)
• A WhatsApp provider (BSP) that has turned on Business app number onboarding in its Embedded Signup flow. Meta lists the provider requirements (Solution Partner or Tech Provider status, working webhooks, Embedded Signup with session logging); they are the provider's job, not yours.
• Your phone with the WhatsApp Business app open during setup, so the sync can run.

How connecting works#

1. 1

   Choose to connect your existing account

   In your provider's Embedded Signup flow, pick the option to connect your existing WhatsApp Business app account, and enter its phone number. WhatsApp shows you a verification code; copy it.

2. 2

   Open the message in the Business app

   You receive a message from the official Facebook Business account in the app. Tap Connect, then Connect to the Business Platform.

3. 3

   Decide about chat history

   Tap Confirm in the app. This step gives you the option to share your chat history with the provider.

4. 4

   Paste the code and finish

   Paste the verification code and complete the rest of the sign-up flow. When onboarding is done, the Business app refreshes and shows that the number is connected to the API.

5. 5

   Keep the app open while it syncs

   The provider now pulls your contacts and (if you agreed) your history. This can take several minutes, depending on how much history you have and your internet speed.

What gets synced#

What changes in the Business app#

Some app features are switched off once the number is connected to the API. Others stay in the app but are not available through the API.

Linked devices#

You can link up to four companion devices ("linked devices") to the Business app. When you connect to the API, all companion devices are unlinked; you can link them again afterwards. Every companion is supported except WhatsApp for Windows and WhatsApp for WearOS. Messages viewed on an unsupported companion show placeholder text asking the person to check their main phone.

Billing and the 24-hour window#

A window only opens when a customer messages you after you are connected. If a customer wrote to you just before onboarding, the API side can only answer them with a template.

Limits#

• Throughput is fixed at 20 messages per second for a number used on both the Business app and the API.
• The provider can't deregister a Coexistence number through the API. Disconnecting is done from the app (below).
• If you previously worked with another provider and still share its credit line, you may see an error when switching to a new provider. Meta has a support guide for resolving it.

Disconnecting#

In the WhatsApp Business app, go to Settings → Account → Business Platform and tap Disconnect Account. Your provider is notified.

The connection can also drop on its own. Meta's reasons include:

Technical details#

For developers integrating this on the provider side:

• Turn it on in Embedded Signup by adding "featureType": "whatsapp_business_app_onboarding" to the extras object of the launch call (on Embedded Signup v5 it is on by default).
• Webhook fields to subscribe to, in addition to the usual ones: account_update, history, smb_app_state_sync (contacts) and smb_message_echoes (messages the business sends from the app or a companion).
• Finish event: the session event is FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING. Its waba_id is the business's existing account ID (Meta converts the account into a Messaging account that keeps the same ID). Skip the phone number registration step: the number is already registered.
• Sync by calling POST /<BUSINESS_PHONE_NUMBER_ID>/smb_app_data once for contacts and once for history. If the business declined to share history, a history webhook with error code 2593109 arrives instead. History webhooks come in phases (day 0–1, 1–90, 90–180) and chunks; progress reaching 100 means the sync is complete.
• Check status:

curl 'https://graph.facebook.com/v26.0/<BUSINESS_PHONE_NUMBER_ID>?fields=is_on_biz_app,platform_type' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

{ "is_on_biz_app": true, "platform_type": "CLOUD_API", "id": "106540352242922" }

is_on_biz_app: true with platform_type: CLOUD_API means the number works on both.

• Disconnects trigger an account_update webhook with a PARTNER_REMOVED event, which may include a disconnection_info object (reason, initiated_by).
• Error 131060 (unsupported message webhook) is expected: it happens when someone messages the business for the first time (often from a click-to-WhatsApp ad; it usually clears within seconds) or uses an unsupported companion device. Tell the business to check the message in the Business app.

Frequently asked#

Gotchas & common mistakes#