WhatsApp Business App coexistence with Cloud API

Coexistence is one of the most important WhatsApp API features for small-business software.

It lets a business keep using the WhatsApp Business App on a phone while also connecting the same number to the WhatsApp Business Platform through an API provider.

That is powerful, but it is not magic. If your product promises coexistence, you need to understand the connection mode, the QR onboarding path, and the Meta-side edge cases that can block it.

What coexistence is

Coexistence means the same WhatsApp Business number can be active in two places:

• The WhatsApp Business App, used by the business on a phone.
• The WhatsApp Business Platform or Cloud API, used by your product for webhooks, automation, workflows, and sending.

For the right customer, this is the best of both worlds. Humans can keep using the app they already know, and your product can still automate parts of the conversation.

When coexistence is the right default

Use coexistence when:

• The customer already uses WhatsApp Business App.
• Human replies still happen from the phone.
• The business wants light automation, routing, notifications, or AI assistance.
• The customer is small enough that forcing an API-only migration would create friction.
• Your product needs to observe messages while the business keeps its current workflow.

This is common for local services, clinics, real estate teams, hospitality, appointment-based businesses, and vertical SaaS products selling into owner-operated teams.

When dedicated Cloud API is better

Use dedicated Cloud API when:

• The phone app is not needed.
• The product needs high-volume sending.
• The connection must be as stable as possible.
• Your product owns all routing, automation, and human inbox behavior.
• The number was created for the API product from the start.

In Kapso docs, coexistence is documented as convenient but less stable than a dedicated Cloud API connection. Dedicated connections are built for scale. Coexistence is built for a mixed human plus API workflow.

The onboarding path

The coexistence path should be QR-based.

In Kapso, the customer chooses the WhatsApp Business App connection option, opens Meta embedded signup, selects the relevant business assets, enters the phone number already active in the WhatsApp Business App, and then scans a QR code from the phone app.

If Meta sends the user into SMS or voice verification instead of the QR-based Business App path, stop. That is usually the wrong connection mode. Restart from Kapso and choose WhatsApp Business App.

This distinction matters because SMS verification is the dedicated-number path. Coexistence is a pairing path.

If the QR step expires or the customer closes the popup, restart the connection flow instead of trying to continue from a half-finished browser state.

What can go wrong

Most coexistence failures are not caused by a bad webhook handler.

Common blockers include:

• The number was previously connected as dedicated Cloud API.
• The number is still attached to another provider.
• An old partner remains in WhatsApp Manager.
• The WABA lives in a different Business Portfolio than expected.
• Meta still has residual ownership or asset-linking state.
• Meta shows provider-sharing, ownership, or eligibility errors during embedded signup.
• The flow asks for SMS/voice verification instead of QR pairing.
• The Business App account is too new or not active enough for Meta eligibility.

The practical support question is: does Meta still think this number belongs to another app, partner, WABA, or portfolio?

Meta does not expose a simple public threshold for every eligibility decision. If a newly created Business App account is blocked, treat it as an eligibility issue to verify with Meta context, not as a deterministic Kapso-side state you can force through retries.

Cleanup before retrying

Before asking the customer to retry the same flow again, check the old ownership path.

A useful cleanup order is:

1. Disconnect old providers in the WhatsApp Business App under business-platform connections.
2. Remove old partners from the WABA’s Partners tab in WhatsApp Manager.
3. Check whether the WABA lives under a different Business Portfolio.
4. Remove stale WABA or portfolio links when Meta allows it.
5. Wait a few minutes for Meta-side cleanup to settle.
6. Restart the Kapso flow and choose WhatsApp Business App.

Steps 1 and 2 are usually done by the customer or a Meta admin in the WhatsApp Business App and WhatsApp Manager. Steps 3 and 4 may require the customer, Kapso support, or both, depending on who has access to the Business Portfolio.

Repeated retries without cleanup can waste days because the visible error is often downstream of an old Meta-side attachment.

History sync limitations

Coexistence can import or sync existing conversation history, but there are limits.

One product-observed pattern is that older imported media messages can remain as media_placeholder because Meta may not provide separate media asset IDs for older history items. If fresh live media works and phone/webhook health is green, older placeholders are usually a history-sync limitation, not proof of a live webhook outage.

That is exactly the kind of edge case your customer success team should know before promising “all history will appear perfectly.”

What to promise customers

Good promise:

You can keep using WhatsApp Business App while our product connects automation and visibility through the API. Some Meta eligibility and prior-provider cleanup can affect onboarding.

Risky promise:

Your existing WhatsApp app number will always connect instantly with no migration work.

Coexistence is valuable because it respects the way small businesses already work. It is risky only when the product hides the Meta constraints until support has to explain them.

How Kapso fits

Kapso supports both dedicated and coexistence onboarding paths.

For SaaS teams, that means you can choose the right connection mode per customer: dedicated for API-owned automation, coexistence for customers who need the Business App and API together.

Kapso also gives you the rest of the operating layer: connection links, connected-number records, webhooks, conversations, Workflows, inbox, and support visibility when onboarding gets stuck.