Home WhatsApp | Connection, templates and sending How to connect a WhatsApp number with coexistence (App + API)

How to connect a WhatsApp number with coexistence (App + API)

Last updated on May 08, 2026

When to use

  • You already use the number on the WhatsApp Business App (mobile) and want to continue using it

  • You want to test the API and automations without giving up manual use via mobile

  • Your team (salespeople, consultants, account managers) needs to continue using the mobile

  • You want a gradual transition to the API without disrupting current operations

Important limitation of coexistence: unsupported devices

Meta has an official limitation in the coexistence model: messages exchanged through WhatsApp Desktop (Windows) or through WhatsApp on WearOS do not arrive in Cloud Chat — even if they appear on the phone, they also do not reach the recipient. This limitation only affects coexistence; in the non-coexistence model (exclusive API), the problem does not exist.

Typical customer report:

Messages sent by the agent are not reaching the customer.

Customer messages appear on the phone but not in Cloud Chat.

Technical details in the Meta official documentation — in summary, these apps do not trigger the webhook smb_message_echoes that the API uses to mirror the conversation.

How to work around

Switch to the NON-coexistence model (exclusive API): all messages pass through the API, there is no more device conflict, and the number stops working on the mobile.

Step-by-step guide: How to connect a WhatsApp number via official API (without coexistence).

Prerequisites

Starting integration without validating the points below may result in number loss, block by Meta, verification errors, or the need to redo the entire setup.

Migrating an existing number? Read the migration guide first — mandatory reading.

If the number you want to connect is already active on another support platform or provider (BSP), DO NOT start the Embedded Signup process before reading:

Migrating WhatsApp to Cloud Chat from another support platform

Skipping this step may result in:

  • Verification failure and stuck migration

  • Inability to release the number from the previous provider

  • Having to redo the entire setup from scratch

The migration guide shows all the Meta prerequisites (WABA ownership, Two-Step Verification, Business Manager status, payment method, message history) that must be validated before starting the integration in Cloud Chat.

New number? You need to warm it up before trying to integrate.

Meta evaluates the usage history of the number before authorizing the connection via API. Newly created numbers, without history on the WhatsApp Business App, may be blocked immediately in the Embedded Signup — Meta returns the error:

"Your phone number is not qualified to connect to the WhatsApp Business platform. More activity in the WhatsApp Business app is required to determine qualification."

How to warm up before integrating:

  • Use the number on the WhatsApp Business App (mobile) for several days/weeks, receiving real conversations

  • Promote the number on your channels (website, social media, email) to generate organic entry

  • Respond within the 24-hour window, without spam, repeated messages, or suspicious links

After warming up, the number enters the API with better tier and Quality Rating, and the Embedded Signup proceeds without the above error.

Official Meta documentation: Messaging Limits · Quality Rating.

Validating Business Portfolio status

The Business Portfolio must have the status "Verified" in Meta. This means Meta has recognized and validated your company's identity.

Why does this matter? Without verification, you are subject to very low sending limits (up to 250 messages/day), cannot migrate numbers from other providers, and may have restrictions on API functionalities. Verification is the first requirement for healthy operation on Meta’s platform.

How to verify:

  1. Visit business.facebook.com/settings/info
  2. Check the Verification Status field
  3. It should be "Verified" âś…

If it shows "Not Verified" or "Pending", click Start Verification and follow the process with company documents and domain validation before proceeding.

Not using WhatsApp Business App on mobile?

Coexistence is designed for those maintaining an active number on the mobile (WhatsApp Business App) alongside the API. If you won't use the number on the mobile — only in Cloud Chat / API — this model doesn't make sense. Use the non-coexistence method:

How to connect a WhatsApp number via official API (without coexistence)

Number already registered and active on WhatsApp Business App (mobile) before starting — coexistence only works if the number was already linked and in use in the app before Embedded Signup. If the number is not yet in the WhatsApp Business App, install the app and register the number.

Step-by-step integration with coexistence

Once all prerequisites above are validated, you can start the integration. Have on hand:

  • Be administrator of the Cloud Chat account

  • Admin access to the Business Portfolio on Meta (necessary to authorize the connection during Embedded Signup)

  • A mobile device with WhatsApp Business App to scan the QR code during synchronization

  • Credit card enabled for USD payments — mandatory for migration or proactive campaigns

Step 1 — Access Cloud Chat Settings

  1. In Cloud Chat, go to Settings

  1. Navigate to Inbox section

Step 2 — Start creating the WhatsApp inbox

  1. Click Add Inbox

  1. Select WhatsApp

  1. In the WhatsApp Channel screen, choose Embedded Signup provider and fill in the desired name for the inbox. Then, click Enter via WhatsApp

Step 3 — Authenticate with Meta

In the Meta pop-up window that opens, log in with the personal Facebook account of the person who has admin access to the company's Business Portfolio in Meta.

The login is not done with a generic corporate email or a "company account" — it’s with the personal Facebook of the person who is an admin of the Meta Business Portfolio. Without this admin permission, the Embedded Signup flow cannot authorize the connection, and the process will get stuck at this step.

  1. After logging in, click Continue

Step 4 — Select Business Portfolio and enable coexistence

  1. Choose the Business Portfolio in Meta and click Next

  1. Select Connect existing WhatsApp Business App and click Next

Step 5 — Verify the number

  1. Select Add a new number, enter the phone number, and verify it

If the number is a landline or digital number, verification must be done via phone call, not SMS.

Step 6 — Synchronize with WhatsApp Business App via QR code

  1. After verification, click Finish to start synchronization with WhatsApp Business App

  2. Open WhatsApp Business on the mobile, scan the QR code, and follow the instructions on the device

Importing contact and message history

During integration, the mobile will receive a notification asking to import the number’s history. Confirming, Meta automatically syncs the message and contact history of the last 6 months to Cloud Chat.

Although import is documented in Meta’s official documentation, recent observations show Meta may not send the complete history at the time of synchronization. Some messages or contacts might not be imported.

This behavior is intermittent and outside Cloud Chat's control, depending on Meta’s delivery. Keep parallel records if necessary.

Step 7 — Set up payment (if applicable)

When payment method registration is MANDATORY:

  • Number migration — always mandatory, no exceptions. Without a valid payment method, Meta does not complete the WABA migration.

  • Proactive messaging (template / campaign / single message via API) — mandatory, because Meta charges for templates sent outside the 24h window.

  • Reopening the 24h window — mandatory. To start a new conversation outside the active window, a template must be sent, which incurs a direct cost charged by Meta to the registered card.

  • Satisfaction survey (CSAT) — CSAT message is also a Meta template. If sent outside the 24-hour window (common if the customer doesn’t respond immediately), without a registered payment method, the CSAT is not sent — the customer does not receive the evaluation question, and the metric remains empty.

Without a valid card registered in WABA, no proactive message is sent, no window is reopened, and no CSAT is delivered outside the window — the number is limited to replying within 24h after the last customer message.

  1. Click Add Payment Method to add the payment method to WABA. For purely reactive support (responding within the 24h window, without proactive sends or migration), click Finish.

Step 8 — Add agents to the inbox

  1. Configure agents who will have access to the new inbox

  1. Click Add Agents

The inbox with coexistence is integrated and ready to use. âś…

Notes

Cloud Chat appears on the mobile as connected device, in WhatsApp Business App → Connected Devices

If someone removes Cloud Chat from the device list on the mobile, the integration will be broken and the entire process must be redone.