> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Coexistence
> Use the WhatsApp Business app and the Telnyx WhatsApp API on the same phone number.
# WhatsApp Coexistence
WhatsApp Coexistence connects a phone number that is already active in the WhatsApp Business app to the Telnyx WhatsApp API. The business can continue its manual conversations in the app while an integration sends automated and template messages through Telnyx.
The Business app and Cloud API share the phone number, but they do not share billing or customer service window state.
## Prerequisites
Before starting:
* Update the WhatsApp Business app to version 2.24.17 or later.
* Keep the phone number registered in the WhatsApp Business app.
* Confirm that the person completing signup has administrator access to the Meta business portfolio that owns the number.
* Use the coexistence option in Embedded Signup. The standard signup flow attempts to register the number for Cloud API-only use.
Do not deregister the phone number from the WhatsApp Business app. Coexistence requires the existing Business app registration.
## Onboard the number
In Mission Control, open **Messaging > WhatsApp**, start Embedded Signup, and select the WhatsApp Business app coexistence option.
Sign in to Meta, choose the option to connect an existing WhatsApp Business app, and enter the phone number that is already active in the app.
Meta sends a message from the official Facebook Business Account to the WhatsApp Business app. Open that message, select **Connect**, select **Connect to the Business Platform**, and confirm the connection.
Choose **Share chats** to synchronize up to six months of individual chat history, or choose **Don't share chats** to continue without history. Copy the verification code shown in the WhatsApp Business app and paste it into the Meta signup window.
Finish the remaining Meta steps. The number stays registered in the Business app and is not registered again through Cloud API.
After Embedded Signup connects the WABA to Telnyx, enable webhook delivery and configure the webhook URL using [Update WABA settings](/api-reference/whatsapp-business-accounts/update-waba-settings). If `webhook_events` is set, include `account_update` to receive coexistence lifecycle events.
Configure the associated messaging profile webhook URL to receive `message.echo` and `message.received` events.
After onboarding, the number enters `sync_pending`. Telnyx accepts synchronization webhooks from Meta and advances the number through the coexistence lifecycle.
Cloud API sends remain blocked until the number reaches `active`.
List the phone numbers connected to the WhatsApp Business Account and confirm that the number reports `is_on_biz_app: true`.
```bash cURL theme={null}
curl "https://api.telnyx.com/v2/whatsapp/business_accounts/WABA_ID/phone_numbers" \
-H "Authorization: Bearer $TELNYX_API_KEY"
```
```javascript Node.js theme={null}
const response = await fetch(
"https://api.telnyx.com/v2/whatsapp/business_accounts/WABA_ID/phone_numbers",
{
headers: {
Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
},
},
);
const result = await response.json();
for (const phone of result.data) {
console.log(
phone.phone_number,
phone.is_on_biz_app,
phone.coexistence_state,
phone.sync_deadline,
);
}
```
```python Python theme={null}
import os
import requests
response = requests.get(
"https://api.telnyx.com/v2/whatsapp/business_accounts/WABA_ID/phone_numbers",
headers={"Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}"},
timeout=10,
)
response.raise_for_status()
for phone in response.json()["data"]:
print(
phone["phone_number"],
phone["is_on_biz_app"],
phone["coexistence_state"],
phone["sync_deadline"],
)
```
The phone-number response exposes these coexistence fields:
Use `GET /v2/whatsapp/phone_numbers/{phone_number}` to retrieve one number and inspect its synchronization progress. The phone-number list operations do not populate `sync_progress`.
| Field | Meaning |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `is_on_biz_app` | `true` when the number is connected to both the WhatsApp Business app and Cloud API. |
| `coexistence_state` | Current lifecycle state. Standard Cloud API numbers return `null`. |
| `sync_deadline` | Deadline for initiating the current synchronization cycle. It is `null` when no deadline applies. |
| `sync_progress` | Contact and history synchronization status. `GET /v2/whatsapp/phone_numbers/{phone_number}` populates it while the number is in `syncing`. |
## Lifecycle and send eligibility
| State | Meaning | Cloud API sends |
| ----------------------- | ---------------------------------------------------------------------- | ------------------------ |
| `pending_onboarding` | Embedded Signup has started but coexistence onboarding is not complete | Blocked |
| `sync_pending` | Onboarding completed and synchronization has not started | Blocked |
| `syncing` | Meta synchronization is in progress | Blocked |
| `sync_complete` | Synchronization completed and activation is being finalized | Blocked |
| `active` | Coexistence is ready | Allowed |
| `history_declined` | The business declined history sharing while onboarding continues | Blocked until activation |
| `sync_deadline_expired` | Required synchronization was not initiated before the deadline | Blocked |
| `offboarded` | Meta offboarded the coexistence connection | Blocked |
| `disconnected` | The business removed Telnyx as its partner | Blocked |
The synchronization deadline is 24 hours from onboarding or reconnection. If it expires, disconnect the integration and complete Embedded Signup again.
## Messaging behavior
Messages sent manually from the WhatsApp Business app produce a [`message.echo`](/docs/messaging/whatsapp/coexistence/webhooks#messageecho) webhook. Treat the event as outbound activity.
Coexistence webhooks provide best-effort conversation visibility, not a complete message archive. Unsupported companion clients do not produce all expected webhooks. Do not use this event stream as the only system of record for a conversation.
Business app messages:
* Do not open or extend the Cloud API 24-hour customer service window.
* Do not create a Telnyx billing event.
* Do not trigger inbound opt-out or autoresponse processing.
Cloud API messages continue to follow the standard WhatsApp pricing and customer service window rules. See [Send WhatsApp messages](/docs/messaging/whatsapp/send-messages).
## Pricing
Messages sent from the WhatsApp Business app and delivered as `message.echo` are free. Telnyx does not create a billing event, and Meta does not charge for the mirrored app message.
Messages sent through Cloud API continue to incur the standard Telnyx and Meta charges that apply to their message category and destination. See [WhatsApp pricing](https://support.telnyx.com/en/articles/13986484-whatsapp-pricing-on-telnyx).
## Disconnect coexistence
The WhatsApp deregistration API cannot deregister a coexistence number. Disconnect it from the WhatsApp Business app:
1. Open **Settings** in the WhatsApp Business app.
2. Select **Account**.
3. Select **Business Platform**.
4. Select **Disconnect**.
Telnyx processes Meta's partner removal event and transitions the number to `disconnected`.
## Limitations
| Capability | Coexistence behavior |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Throughput | Fixed at 20 messages per second for a coexistence-enabled number. |
| Individual chats | Supported. Up to six months of recent chat history can be synchronized when the business shares it. |
| Contacts | WhatsApp contacts can be synchronized. |
| Group chats | Continue in the Business app but are not synchronized to Cloud API. |
| Broadcast lists | Existing lists become read-only. New broadcast lists cannot be created in the Business app. |
| Disappearing messages | Not supported while coexistence is enabled. |
| View-once messages | Not supported while coexistence is enabled. |
| Live location | Not supported while coexistence is enabled. |
| Voice and video calls | Continue in the Business app but are not supported through Cloud API. |
| Business and messaging tools | Catalog, orders, status, greetings, away messages, quick replies, and labels remain available in the Business app but are not synchronized to Cloud API. |
| Business profile | Remains available in the Business app but is not synchronized to Cloud API. |
| Channels | Remain available in the Business app but are not synchronized to Cloud API. |
| Companion devices | Existing companion devices are unlinked during onboarding. Supported devices can be linked again afterward. |
| Windows and WearOS companions | Messages sent from these clients might not produce webhooks. |
| Conversation visibility | Best-effort only. Do not use coexistence webhooks as a complete system of record for every Business app conversation. |
## Get support
Include the following identifiers when contacting [Telnyx Support](https://support.telnyx.com):
* Telnyx organization ID
* WhatsApp Business Account ID
* Meta phone number ID
* Phone number in E.164 format
* Telnyx message ID and Meta `wamid`, when the issue involves a message
* Approximate event time and timezone
For lifecycle problems, also include the current coexistence state and the Meta lifecycle event, when available.
If Telnyx Support asks you to open a Meta Direct Support case, use the routing that matches the problem:
| Problem | Question Topic | Request Type |
| ------------------------------ | ------------------------------------------------- | ---------------------------------------------------- |
| Coexistence onboarding | `WABiz: Onboarding` or `TechProvider: Onboarding` | `Embedded Signup - Coexistence Onboarding` |
| Synchronization API or webhook | `WABiz: Cloud API` | `Coexistence Data Synchronization APIs and Webhooks` |
See Meta's [onboarding guide for WhatsApp Business app users](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/) for the current support categories.
## Related documentation
Handle Business app echoes and lifecycle changes.
Review the standard WhatsApp onboarding flow.