WhatsApp coexistence: how to use the same number in the Business app and the official API

Updated on October 29, 2026

Coexistence is the Meta feature that connects a number already active in the WhatsApp Business app to the WhatsApp Cloud API without removing it from the app. After onboarding, the business keeps chatting from the phone and, at the same time, sends and receives messages through the API, with history synced between the two. The connection is made through a Meta partner’s Embedded Signup and comes with limits: a fixed throughput of 20 messages per second, some app features turned off, and the need to open the app regularly.

In Meta’s documentation, the feature is called “Onboard WhatsApp Business app users” (Onboard WhatsApp Business app users), and Meta notes that it is sometimes referred to as “Coexistence” in support channels and partner documentation.

Why coexistence exists

Before it, putting a number on the WhatsApp Business API meant deleting it from the app. The Cloud API phone numbers documentation still says that numbers already in use with WhatsApp cannot be registered unless they are deleted first; coexistence, documented on the onboarding page, is the route for WhatsApp Business app numbers. For small businesses, the old route meant losing chat history and the phone-based way of working.

With coexistence, the Business app number also becomes an API number. The owner keeps replying from the phone, and a connected system (CRM, chatbot, AI agent, notification platform) starts operating on the same number.

What happens to the account during onboarding

When the customer finishes the flow, Meta converts the existing WhatsApp Business account into a compatible messaging account. In practice:

• The ID returned by Embedded Signup is the same numeric ID the account had before the conversion: in the waba_id field in version 4, and in the messaging_account_ids field in version 5.
• No separate messaging account is created for the partner.
• The WhatsApp account tied to the number and the converted messaging account are shared with the partner, but stay in the customer’s business portfolio.
• The phone number registration step is skipped, because the number is already registered.

Since September 23, 2026, Meta splits the old WABA into a WhatsApp account (the number) and a messaging account (templates, billing, webhooks). If that structure is new to you, see WhatsApp account vs. messaging account.

Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →

Requirements

Requirement	Detail
App version	WhatsApp Business app 2.24.17 or later on the customer’s phone
Who onboards	A Meta Solution Partner or Tech Provider
Flow	Embedded Signup with session logging
Webhooks	An endpoint able to receive and process the extra fields (see below)
Embedded Signup version	Versions 2 and 3 are discontinued; in version 5 (October 20, 2026), coexistence is on by default

The last row changed recently. Meta announced that Embedded Signup versions 2 and 3 would be deprecated on October 15, 2026, and on October 20, 2026 it released version 5, where onboarding WhatsApp Business app users is enabled by default. Older integrations need to be updated.

Meta’s onboarding page does not list country restrictions for the feature.

How the flow works for the customer

1. In Embedded Signup, the customer chooses to connect an existing WhatsApp Business app account and enters the number.
2. WhatsApp shows a verification code.
3. The customer receives a message in the app from the official Facebook Business account and taps Connect, then Connect to the Business Platform.
4. The app asks whether they want to share their chat history with the partner.
5. The customer pastes the code and completes the flow.

On the partner side, Embedded Signup returns the IDs and an exchangeable token code, like any onboarding. The difference is the session event, which in version 4 looks like this:

{
  "data": { "waba_id": "<CUSTOMER_WABA_ID>" },
  "type": "WA_EMBEDDED_SIGNUP",
  "event": "FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING"
}

In version 5, the event keeps the same name when the number comes from the app (is_on_biz_app: true), but data changes: waba_id gives way to messaging_account_ids, alongside phone_number_id, is_on_biz_app and business_id.

In version 4, you opt in to the feature with featureType inside the extras object of the Embedded Signup launch code (FB.login). In this version, sessionInfoVersion is ignored and is always 3:

FB.login(fbLoginCallback, {
  config_id: "<CONFIGURATION_ID>",
  response_type: "code",
  override_default_response_type: true,
  extras: {
    setup: {},
    featureType: "whatsapp_business_app_onboarding"
  }
});

In version 5 (version: "v5" in extras), featureType is no longer needed, because the option is on by default. To turn it off, add the feature to features with enabled: false; according to Meta, the opt-out applies even if featureType is also passed:

FB.login(fbLoginCallback, {
  config_id: "<CONFIGURATION_ID>",
  response_type: "code",
  override_default_response_type: true,
  extras: {
    version: "v5",
    features: [
      { name: "whatsapp_business_app_onboarding", enabled: false }
    ]
  }
});

Sync: the 24-hour deadline

After onboarding, the partner has 24 hours to sync contacts and history. If the deadline is missed, the customer has to offboard and go through the flow again. Each sync can only be requested once.

Sync uses the SMB App Data API (smb_app_data), first for contacts and then for message history:

curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'

curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/smb_app_data" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "sync_type": "history" }'

The response includes a request_id, worth storing for support tickets. History covers up to six months of one-to-one chats and is only sent if the business agreed to share it; if it declined, the history webhook arrives with error 2593109. Meta recommends asking the customer to keep the app open during the process. The full breakdown of phases, chunks and media is in what syncs and what doesn’t in coexistence.

Additional webhooks

On top of the fields you already subscribe to, coexistence requires four messaging account fields:

Field	What it carries
account_update	Account lifecycle changes, including disconnection (PARTNER_REMOVED)
history	Past messages sent and received by the customer
smb_app_state_sync	New and existing contacts from the app
smb_message_echoes	Messages the customer sends from the app after onboarding

smb_message_echoes is what keeps your system up to date: when the owner replies from the phone, the event arrives and you store the message in the contact’s history. Without it, your system only sees half of the conversation.

To understand the event structure and build a robust endpoint, see WhatsApp API webhooks: a practical guide.

What changes in the WhatsApp Business app

Meta publishes a table comparing features before and after onboarding. The main points:

App feature	After onboarding	Available through the API?
One-to-one chats	Continue; editing and revoking messages become supported	Yes, mirrored between app and API
Contacts	No change	Yes, synced
Groups	No change in the app	Not synced
Disappearing messages	Turned off for one-to-one chats	No
View once	Disabled	No
Live location	Disabled	No
Broadcast lists	Disabled; existing lists become read-only	No
Voice and video calls	No change in the app	No
Catalog, orders, status	No change in the app	No
Greeting, away messages, quick replies, labels	No change in the app	No
Linked devices	Unlinked during onboarding; can be linked again	Except WhatsApp for Windows and WearOS

About linked devices: the app supports up to four companion devices. Messages that a WhatsApp user sends from an unsupported companion device do not trigger the messages webhook, so they do not appear in your system.

The Groups API is also not available for WhatsApp Business app numbers, according to the groups documentation.

Limits that affect operations

Throughput fixed at 20 mps

Numbers that use the app and the API at the same time have a fixed throughput of 20 messages per second. Regular Cloud API numbers start at 80 mps and can be automatically upgraded to up to 1,000 mps when eligible. For large notification sends, this matters.

Inactivity drops the connection

The account_update webhook with the PARTNER_REMOVED event reports the reason for the disconnection. Documented reasons include:

• PRIMARY_INACTIVITY: the primary device was inactive for about 14 days;
• COMPANION_INACTIVITY: a companion device was inactive for about 30 days;
• BUSINESS_DOWNGRADE: the number was registered on regular WhatsApp (Messenger);
• CHANGE_NUMBER and USER_RE_REGISTERED: number change or new registration on another device;
• ACCOUNT_DISCONNECTED: the account was disconnected due to an enforcement action or because the business deleted its WhatsApp account.

In practice, tell the customer to open the app on the primary phone regularly. Handle PARTNER_REMOVED in your system and alert the team, instead of finding out from messages that stopped going out.

Disconnection only from the app

The Deregister endpoint does not work for numbers in coexistence. The customer disconnects from the app, under Settings > Account > Business Platform > Disconnect Account.

Error 131060 on the first message

Meta documents that incoming messages may arrive with error 131060 when a user writes for the first time (common after an ad click) or uses an unsupported companion device. In the first case, the error usually resolves within seconds. In the second, tell the business to check the message in the app.

Pricing and the customer service window in coexistence

• Messages sent from the app remain free.
• Messages sent through the API follow Cloud API pricing, by category and country.
• The 24-hour customer service window only opens for messages received after onboarding. If the customer wrote before, the reply through the API must be a template.
• Messages sent from the app do not open, extend or affect API windows or pricing.

For numbers in Brazil, rates since October 1, 2026 are R$ 0.3217 per marketing message and R$ 0.0350 per utility, authentication or service message (BRL, the Brazilian real). Each business phone number gets 1,000 free delivered service messages per month, charged from the 1,001st, and utility templates sent inside the customer service window are now charged (they stay free only inside an open free entry point window). Details in WhatsApp API pricing in Brazil; for other markets, see WhatsApp API pricing by country. The source is Meta’s official pricing page.

How to check whether a number is in coexistence

Request the is_on_biz_app and platform_type fields on the number:

curl "https://graph.facebook.com/<API_VERSION>/<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" }

If is_on_biz_app is true and platform_type is CLOUD_API, the number works in both the app and the API.

When coexistence is worth it

It fits businesses whose customers already talk to the app number and that want to automate part of their support or notifications without changing numbers. It works well for clinics, shops and service providers where the owner or team still replies from the phone. If you plan to plug a CRM into the number, read coexistence with a CRM and messaging limits.

It is a weaker fit when:

• your send volume needs more than 20 messages per second;
• your operation depends on broadcast lists, disappearing messages or groups through the API;
• nobody can keep the primary phone active.

Coexistence and Vectalk

Vectalk offers coexistence: the number stays in the WhatsApp Business app and also works through the WhatsApp Cloud API. Numbers are connected through Meta’s Embedded Signup, and payloads and webhooks are the same as in Meta’s documentation, so history, smb_app_state_sync and smb_message_echoes arrive at the URLs you register with POST /api/webhooks. Billing is a monthly fee plus prepaid credit: Vectalk attaches its own credit line to the number, each delivered message is deducted from the balance, and you do not need to add a card on Meta. See the documentation.

To create an account, use the sign-up page; questions can go through the contact page. If you are still deciding between the API and the app, the guide to the official WhatsApp API helps compare them.

Frequently asked questions

Does coexistence work with regular WhatsApp (Messenger)?

No. The feature is for numbers in the WhatsApp Business app. If the number is on regular WhatsApp, you can move it to the Business app first, or delete the app account and register the number directly on the Cloud API; see how to use an existing WhatsApp number with the API.

Will I lose my chat history?

Not in the app. For the system connected to the API, Meta lets you sync up to six months of one-to-one chats, if the business allows it, within 24 hours of onboarding. Groups are not synced.

Can I keep sending messages from my phone?

Yes. Messages sent from the app remain free and show up in the connected system through the smb_message_echoes webhook.

Can I set up coexistence with a direct integration, without a partner?

Meta’s documentation lists being a Solution Partner or Tech Provider as a requirement. A business that only integrates its own number usually does it through a provider.

Why did my number disconnect from the API on its own?

Check the PARTNER_REMOVED event in the account_update webhook. The most common reason is the primary phone being inactive for about 14 days (PRIMARY_INACTIVITY). Reconnecting with the same partner triggers the ACCOUNT_RECONNECTED event.

---

Sources checked on October 29, 2026: Onboard WhatsApp Business app users, Business phone numbers, Groups API, Pricing, Changelog, Account model evolution, Embedded Signup versions, Version 5.