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

The steps below describe direct customer onboarding in the Telnyx Portal. Tech Providers can onboard coexistence numbers through a hosted signup created with signup_type set to coexistence, or through the custom integration with Meta’s coexistence configuration.

Start coexistence signup

In the Telnyx Portal, open Messaging Suite → WhatsApp Messaging, go to the Business Accounts tab, select Add Account, and select the WhatsApp Business app coexistence option before starting Embedded Signup. Connect WhatsApp Business and Add Number start the standard signup flow, not coexistence.

Complete the Meta flow

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 whether to share chat history

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.

Configure customer webhooks

After Embedded Signup connects the WABA to Telnyx, enable webhook delivery and configure the webhook URL using Update WABA settings. If webhook_events is set, include account_update to receive coexistence lifecycle events.Assign the phone number to a messaging profile and configure the profile webhook URL to receive message.echo and message.received events. Without a messaging profile, message.echo events are not delivered.

Wait for synchronization and activation

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.

Verify the number

List the phone numbers connected to the WhatsApp Business Account and confirm that the number reports is_on_biz_app: true.

curl "https://api.telnyx.com/v2/whatsapp/business_accounts/WABA_ID/phone_numbers" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

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,
  );
}

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

Meta allows synchronization only within 24 hours of completing onboarding in the Meta flow. After that window, Meta rejects the synchronization request and the number cannot reach active. Disconnect the number in the WhatsApp Business app and complete coexistence signup again to start a new window.

Messaging behavior

Messages sent manually from the WhatsApp Business app produce a message.echo 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.

Throughput

Meta limits each coexistence-enabled phone number to 20 Cloud API messages per second. The limit includes inbound and outbound Cloud API messages of every type. Meta documents this as Cloud API throughput and does not state that messages sent directly from the WhatsApp Business app consume it. When Cloud API traffic exceeds the limit, Meta returns error 130429 in the send response or a subsequent message status webhook. Telnyx reports the message as failed with error code 40011. Retry with backoff and reduce the sending rate before retrying. See Meta’s Cloud API throughput documentation.

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.

Disconnect coexistence

The WhatsApp deregistration API cannot deregister a coexistence number. Disconnect it from the WhatsApp Business app:

Open Settings in the WhatsApp Business app.
Select Account.
Select Business Platform.
Select Disconnect.

Telnyx processes Meta’s partner removal event and transitions the number to disconnected.

Limitations

Capability	Coexistence behavior
Throughput	Fixed at 20 Cloud API 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:

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 for the current support categories.

Coexistence webhooks

Handle Business app echoes and lifecycle changes.

WhatsApp Embedded Signup

Review the standard WhatsApp onboarding flow.

Tech Provider Embedded Signup

Implement coexistence through a custom Tech Provider integration.

Getting Started

Sending Messages

Coexistence

Calling

Management API

Sending API

For AI Agents

WhatsApp Coexistence

WhatsApp Coexistence

Prerequisites

Onboard the number

Lifecycle and send eligibility

Messaging behavior

Throughput

Pricing

Disconnect coexistence

Limitations

Get support

Coexistence webhooks

WhatsApp Embedded Signup

Tech Provider Embedded Signup

​WhatsApp Coexistence

​Prerequisites

​Onboard the number

​Lifecycle and send eligibility

​Messaging behavior

​Throughput

​Pricing

​Disconnect coexistence

​Limitations

​Get support

​Related documentation

Coexistence webhooks

WhatsApp Embedded Signup

Tech Provider Embedded Signup

WhatsApp Coexistence

Prerequisites

Onboard the number

Lifecycle and send eligibility

Messaging behavior

Throughput

Pricing

Disconnect coexistence

Limitations

Get support

Related documentation