---
title: WhatsApp Business Coexistence + API: The Complete Guide
description: WhatsApp coexistence: use the same number in the WhatsApp Business app and on Meta's official API. Requirements, 6-month history, limitations, and how to turn it on.
date: 2026-09-06
updated: 2026-09-16
category: coexistencia
tags: coexistence, whatsapp business, official api, conversation history, embedded signup
author: gabriel-miranda
cover: /blog-assets/covers/coexistencia-whatsapp-business-api.jpg
coverAlt: Team using a laptop and smartphone in an office
coverSource: https://www.pexels.com/photo/4968560/
ptSlug: coexistencia-whatsapp-business-api
---

Coexistence is the Meta feature that lets a single number work at the same time in the WhatsApp Business app on the phone and on the official WhatsApp API. The app stays installed, with your usual conversations, and a system starts receiving and sending messages through that number. You do not need a new SIM card, you do not lose the number, and you can bring up to 6 months of history into the platform. In exchange, you accept some limitations Meta imposes on this mode, and the main one is a pace of 20 messages per second.

This guide explains what coexistence is, what changes day to day, what Meta requires, what it takes away from the app, and how to turn it on in minutes.

## What is coexistence, in a short answer

In the developer documentation, Meta calls the feature "Onboard WhatsApp Business app users": connecting to the API a number that is already in use in the WhatsApp Business app. In commercial material and among partners, the name is "WhatsApp Coexistence." It is the same thing.

The [official WhatsApp API](/en/blog/official-whatsapp-api) is the Cloud API, the door Meta opens so that systems can send and receive messages through a business number. Until recently, using that door meant giving up the app. Coexistence removes that choice: the number gets two ends, the app and the API, and both see the same conversations.

For anyone with a store, a clinic, a school, or an online course, the difference is practical. The number customers already know stays on the team's phone and, at the same time, gains what the app alone cannot give: bulk sending with Meta-approved messages, integration with the company's system, and automatic replies to people who write in.

## How it used to be: an API-only number, no app on the phone

Before coexistence, a number could only be in one place: registered in the WhatsApp Business app or registered on the Cloud API. Connecting to the API meant taking the number out of the app, and from then on it only answered through software.

That created three problems for a small business. The history stayed on the phone, and the platform started from zero. The team that handled customers from the phone had to switch to a dashboard, and many gave up on the API because of that, or bought a new SIM just for it and ran two numbers. And the migration was irreversible the moment it happened: if something went wrong midway, the number was offline at both ends.

Coexistence eliminates all three at once. The number does not move. It gains a second end.

## What coexistence changes

### The app stays on the phone, with your usual conversations

After connecting, the WhatsApp Business app stays installed on the same device, logged in to the same number, with the same conversations and contacts. The team that handles customers from the phone does not need to change habits. The only visible difference inside the app is a new screen in Settings, called Business Platform, which shows the connected partner and lets you disconnect. Apart from that, the app works as before, except for the features Meta turns off in this mode, listed further down.

### The API receives and sends through the same number

From the moment of connection, every message that arrives at the number is delivered to the app and the API at the same time. Nothing changes for the customer who writes in. On the system side, the number now answers through two paths:

- **Sending through the API:** the system sends a message, it goes out from your number and shows up in the app conversation too. Whoever has the phone in hand sees the message sent by the system as if it were theirs.
- **App echo:** when someone on the team replies from the phone, Meta notifies the API with an event called `smb_message_echoes`, the "echo" of the message sent by the app. That is what lets the dashboard show the whole conversation, with what went out through the API and what went out from the phone.

In Frame Conexa, the dashboard builds the conversation from both sources: a message sent from the phone at 9:00 and a system reply at 9:05 appear on the same timeline. Whoever consumes the API receives the echo through the outbound webhook, in the same format as other events:

```json
{
  "type": "smb_message_echoes",
  "clientId": "8",
  "instanceId": "6ed76b84-4d65-4f3d-88c1-8d4174bdce73",
  "customerId": null,
  "customerRef": null,
  "payload": {}
}
```

> **Note:** according to Meta, messages sent by the app remain free and do not open, extend, or affect the API's windows. The 24-hour window is opened by the customer, when they write. So a reply given from the phone to someone who arrived through an ad does not open the free 72-hour window: to get that window, the first reply has to go out through the API.

The sending rule is the same as for any number on the Cloud API: free-form messages only inside the [24-hour window](/en/blog/whatsapp-24-hour-window) opened by the customer; outside it, only a Meta-approved message, called a template. Coexistence does not relax that rule. The phone app can still write at any time, because the window rule applies to the API, not to the app.

## What are Meta's official requirements?

Meta publishes the requirements on its page about onboarding WhatsApp Business app users. There are few, but two of them tend to sink attempts.

| Requirement | Whose rule | What happens if it fails |
|---|---|---|
| WhatsApp Business app version 2.24.17 or later | Meta | The flow rejects the number at the eligibility step |
| Number active in the app, on the primary device | Meta | Without an active app there is nothing to coexist with |
| Tech Provider or Solution Partner with Cloud API, webhooks, and Embedded Signup approved | Meta | Only a partner in that condition can offer the feature |
| Primary device active, with the app opened from time to time | Meta | About 14 days without activity disconnects the integration |
| Keep the app open during the history import | Meta, as guidance | The import may end up incomplete |

About the partner: Meta only enables coexistence for those who passed its App Review with the management and messaging permissions, and implemented the webhooks required for this mode. Frame Conexa is a verified Tech Provider, and the connection flow is Meta's own [Embedded Signup](/en/blog/whatsapp-embedded-signup), opened inside the dashboard. The WhatsApp password never goes through the partner; what the partner receives is an authorization.

### App version, active phone, and what happens after 14 days without opening it

The app version is the simplest requirement to check and the easiest to forget. Update WhatsApp Business in your phone's app store before you start.

The active phone is the requirement that surprises people later. In coexistence, the primary device remains the root of the number. If it stays inactive for about 14 days, Meta disconnects the integration with an event called `PRIMARY_INACTIVITY`, and the number goes back to living only in the app. Nothing is lost on the phone, but the API stops receiving and sending until a new connection. A SIM card kept in a drawer does not work: the phone has to stay on, with internet, and the app has to be opened now and then. If the intent is a number that nobody operates from a phone, the path is a new API-only number, covered at the end of this guide.

> **Warning:** switching the number to another device and registering it again in the app also undoes coexistence. Meta notifies the partner with an offboarding event, and the Frame Conexa dashboard marks the number as disconnected. Reconnecting means redoing the flow, and the history is only imported during connection. The article on [disconnected coexistence](/en/blog/whatsapp-coexistence-disconnected) lists the six reasons Meta reports and the steps to get back.

## History and contacts: the 6 months Meta shares

This is why coexistence is worth more than it seems. At connection time, the number's owner decides whether to share the history with the partner. If they accept, Meta sends the platform all messages sent and received in the previous 180 days, the "6 months" of the commercial material.

Contacts come along too. Meta syncs all contacts that have WhatsApp through a separate event called `smb_app_state_sync`. That is how the dashboard is born already holding the name and number of the people you talk to, without typing anything.

Two important rules about what arrives:

- **Text comes in full within the 180 days.** Images, audio, and documents only come for messages from the last 14 days. Older messages arrive with the text and without the media.
- **The history is imported once, at connection.** There is no "import again" button later. Anyone who declines sharing at the time and changes their mind later has to disconnect and redo the flow.

In the Frame Conexa dashboard, these messages show up in the conversation as history, marked differently from new messages. They give context to whoever handles the conversation, but they do not reopen sending windows: an old imported conversation does not count as "the customer wrote just now."

### The three import phases and the 24-hour window to sync

Meta delivers the history in three phases, through an event called `history`: first the messages from the last day, then those from day 1 to day 90, then those from day 90 to day 180. The most recent arrive first so the dashboard becomes useful quickly.

The partner has 24 hours, counted from connection, to complete the sync. If it cannot, Meta expects the number to be disconnected. That is why the guidance to keep the app open during the import exists: the phone takes part in sending the data, and a closed app delays the phases.

In Frame Conexa, the Sync step shows the progress of both syncs, conversations and contacts, and keeps the percentage received until Meta reports 100%. If the import stalled, the way out is to open WhatsApp Business on the phone and wait. There is no way to force it from the dashboard, because the device is the one sending the data.

## Which limitations do you need to accept?

This is the part most texts on coexistence hide. Meta turns off some features in the app when the number is connected to the API, and leaves others out of the API. None of these restrictions come from the provider. They all come from Meta, and apply to any partner.

### 20 messages per second and no new broadcast lists

The heaviest limitation is the pace. A Cloud API-only number sends 80 messages per second by default, and Meta raises that automatically for large numbers. A number in coexistence is fixed at 20 messages per second, because the app and the API have to stay in sync.

For customer support, 20 per second makes no difference. For bulk sending, it makes some: a campaign of 5,000 messages takes a little over four minutes at full pace, versus a little over one minute on an API-only number. Frame Conexa respects this cap per number and controls each campaign's pace on its own. In practice, what limits bulk sending is not the pace. It is the [number's capacity](/en/blog/whatsapp-business-api-messaging-limits) set by Meta, the number of different people your portfolio can reach outside the window in 24 hours, and that applies equally in both modes.

Broadcast lists are the second impact. In the app, you can no longer create lists, and the ones that already existed become read-only: you can see them, but you cannot send through them. Anyone who used broadcast lists to notify customers migrates to bulk sending through the API, with Meta-approved messages and the recipient's consent. The guide to [official WhatsApp bulk messaging](/en/blog/official-whatsapp-bulk-messaging) explains that path.

### What changes in the app and what stays outside the API

The table below summarizes the comparison that Meta's official page publishes for numbers in coexistence. The first column says what happens in the phone app; the second, whether the feature goes through the API.

| Feature | In the app, after connecting | Through the API |
|---|---|---|
| One-to-one chats | No change; editing and deleting messages become supported | Yes, mirrored on both sides |
| Contacts | No change | Yes, synced |
| Groups | No change | No, groups are not synced |
| Broadcast lists | You cannot create new ones; existing ones become read-only | No |
| Disappearing messages | Turned off in one-to-one chats | No |
| View once | Turned off in one-to-one chats | No |
| Live location | Turned off in one-to-one chats | No |
| Voice and video calls | No change | No |
| Catalog, orders, and status | No change | No |
| Quick replies, labels, greeting, and the app's marketing tools | No change | No |
| Business profile and channels | No change | No |

Two observations about this list. Groups, calls, and catalog stay on the phone as before, but the system cannot see them: a sale closed by phone call or through the app's catalog does not show up in the dashboard. And everything that stays outside the API continues to be operated by the app, such as the business profile, which on a coexistence number is edited from the phone. Frame Conexa does not charge per message and does not impose a sending limit of its own; what limits you is Meta, through the number's capacity and quality.

> **Important:** Meta changes API billing on 10/01/2026. Free-form messages inside the 24-hour window and utility messages inside the window start being charged per message. The WhatsApp Business app on the phone is not affected, only the API. In coexistence, that means a reply sent from the phone stays free, and a reply sent by the system starts following the table published by Meta. Check the official rate card and the article on [how much the WhatsApp API costs](/en/blog/whatsapp-business-api-pricing).

## How to turn it on in minutes with Frame Conexa

The connection happens inside the dashboard, in five steps: Choose, Prepare, Authorize, Sync, and Test. The authorization itself is Meta's Embedded Signup, in a Meta window.

1. **Choose.** In the dashboard, click Connect WhatsApp and choose "Number already in use on WhatsApp." The other option is "New number, API only."
2. **Prepare.** Update WhatsApp Business on the phone, check that the primary device has internet, and leave the app open.
3. **Authorize.** A Meta window opens. In it you log in with the account that manages the business, choose or create the business portfolio, and choose the WhatsApp Business account and the number. On the phone, the app asks for confirmation and asks whether you want to share history and contacts. Accept if you want the 6 months in the dashboard. The window has a 15-minute limit; after that, the authorization expires and you have to start over.
4. **Sync.** The dashboard receives the authorization, confirms the number is actually in coexistence, enables the events, and tracks the import of conversations and contacts.
5. **Test.** Send the first message to your own phone from the dashboard and check that it also appeared in the app conversation.

If the person holding the phone is a customer of yours, as in the case of an agency, generate a shareable connection link in the dashboard. The customer opens the link, without logging in, and does only the authorization. The number is created in the account of whoever generated the link.

After connecting, the number answers the public API like any other. The first send by code is the same as in the [quickstart guide](/docs/quickstart):

```bash
curl -X POST https://frameconexa.com/api/v1/instances/$FRAME_CONEXA_INSTANCE_ID/messages \
  -H "Authorization: Bearer fc_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"5585999990000","type":"text","text":{"body":"Olá!"}}'
```

Nothing in sending, webhooks, or campaigns changes because of the mode. Coexistence is a decision made at connection time; after that, the number is a number on the Cloud API.

### Error 2388002: "partner already assigned"

The most common error on this path shows up in Meta's window, at the step where you enter the number: "Failed to check phone number eligibility," code 2388002. Nothing reaches the partner, because the authorization dies before being issued. From the outside, it looks like the person gave up.

The cause we measured in production, in August 2026, was an already-assigned partner: an earlier attempt of the flow itself had left the partner with access to the number's WhatsApp Business account. With the partner there, the eligibility check fails on every following attempt.

The fix is in the number owner's Business Manager: Settings, Partners, the partner in question, the WhatsApp account, Manage, Remove access. When you redo the flow, eligibility passes and Embedded Signup itself reassigns the partner.

> **Warning:** do not remove the number from the WhatsApp Business account or delete the account to "start from scratch." Eligibility for coexistence depends on the number's activity history in the app, and restarting that link resets the clock; partners report waits of weeks to months. Undoing the link with the app's disconnect button, or removing the partner's access in Business Manager, does not have that effect.

When the attempt fails before any request exists, the Frame Conexa dashboard records the failure from the browser side, with the error code when Meta provides it. That is how support tells "Meta refused" apart from "the person closed the window."

There is also the case where Meta's window does not even offer coexistence and opens the new-number signup. The causes and fixes are in [coexistence option not showing](/en/blog/coexistence-option-not-showing).

### Why a coexistence number never goes through /register

A technical detail explains why coexistence is safe and why the opposite direction is not.

On the Cloud API, a new number has to be registered with a call named `/register`, with a six-digit PIN. It is what tells Meta "this number is now operated by the API." A number in coexistence is already registered, through the phone app. Calling `/register` on it logs the app out, irreversibly from our side: the number becomes API-only and the phone loses WhatsApp Business.

That is why Frame Conexa never calls `/register` on a coexistence number. If you choose "New number" and Meta returns a number that is actually in the app, the dashboard corrects the mode to coexistence and carries on. The opposite never happens: if you chose coexistence and Meta reports that the number is not in the app, the flow stops and warns you, instead of registering on its own and knocking out the phone app. Going down is reversible; going up is not. The signal checked is the number's `is_on_biz_app` field, which Meta returns after authorization.

## Coexistence or a new API-only number? How to choose

Both modes exist in the dashboard, and the right question is about who will operate the number.

| Criterion | Coexistence | New API-only number |
|---|---|---|
| App on the phone | Stays, with the conversations | Does not exist |
| Number | The one you already use | A new SIM, registered on the API |
| History | Up to 180 days imported | Starts from zero |
| Sending pace | 20 messages per second | 80 per second, with automatic upgrade |
| Groups, calls, and catalog | Stay in the app, outside the API | Do not exist, because there is no app |
| Depends on the phone being on | Yes, about 14 days without activity disconnects | No |
| Business profile | Edited in the app | Edited in the dashboard or through the API |
| Who handles conversations | Team on the phone and the system | Only the system or a dashboard |

Choose **coexistence** when the number is already known to customers, when the team handles customers from the phone and will keep doing so, and when the history matters. That is the case for most stores, clinics, and schools, and it is the only way to migrate to the official API without losing the number or the conversations.

Choose a **new number** when nobody will operate from a phone, when the sending volume justifies the higher pace, or when the number will serve only a system. In this mode the business profile, with photo, description, and address, is edited in the dashboard, because there is no app.

A common path is to have both: the main number in coexistence, for support, and a new API-only number for bulk sending. Frame Conexa sells per number, and each one can be for support or for marketing. Plans are listed in [pricing](/#precos).

If the number has ever been blocked or restricted by Meta, resolve that before connecting: a number with an active restriction does not gain capacity by joining the API. The article on [blocked WhatsApp Business](/en/blog/whatsapp-business-blocked-what-to-do) explains what to do in that case.

## Frequently asked questions

### Does WhatsApp coexistence lose the conversation history?

No. The phone app keeps everything it already had. And, if the number's owner accepts sharing at connection time, Meta sends the platform the messages from the previous 180 days, in three phases, with media only from the last 14 days. The import happens once, during connection; anyone who declines and changes their mind later has to disconnect and redo the flow.

### Can I keep using the WhatsApp Business app on my phone?

Yes. That is the core of coexistence. The app stays on the same device, with the same conversations, and the team can reply through it normally. What goes out from the phone appears in the dashboard as an echo, and what the system sends through the API appears in the app conversation. The 24-hour window rule applies only to what goes out through the API.

### Which functions does the app lose in coexistence?

According to Meta's official page, the app turns off disappearing messages, view once, and live location in one-to-one chats, and stops creating broadcast lists; the lists that already existed become read-only. Groups, calls, catalog, and the app's tools keep working on the phone, but do not go through the API. All of these rules are Meta's, and apply to any partner.

### What happens if I go days without opening the app?

The primary device has to stay active. If it goes about 14 days without activity, Meta disconnects the integration and the number goes back to living only in the app. Nothing disappears from the phone, but the API stops receiving and sending until you redo the connection. Keeping the phone on, with internet, and opening the app now and then prevents this.

### Does coexistence work for bulk sending?

Yes, at the fixed pace of 20 messages per second that Meta imposes on this mode, versus 80 per second on an API-only number. For most campaigns that is a matter of minutes, not of feasibility. What actually limits reach is the number's capacity set by Meta, and it applies equally in both modes. Sending has to use Meta-approved marketing messages and the recipient's consent.

## Next step

If your number is already on WhatsApp Business and you want the official API without giving it up, coexistence is the path, and connecting takes a few minutes. See the [per-number plans](/#precos) and, for the technical side, the [quickstart guide](/docs/quickstart) shows the first send through the API right after connecting.