How WhatsApp embedded signup works for SaaS platforms

If your SaaS product lets customers bring their own WhatsApp number, you need an onboarding flow that is more structured than “paste an API key here”.

WhatsApp is not just an API credential. A real connection has a Meta Business Portfolio, a WhatsApp Business Account, a business phone number, permissions, review state, billing state, webhook subscriptions, and a way for your product to remember which customer owns which number.

Embedded signup is Meta’s hosted flow for collecting that connection from the customer. Kapso turns that into a product primitive: a customer connection link.

The short version

For a SaaS platform, embedded signup is the “connect WhatsApp” flow your customer completes inside a Meta-controlled popup.

The customer logs in with Facebook or Meta business credentials, chooses or creates business assets, accepts the required terms, grants access, and connects a WhatsApp phone number. When the flow finishes, your platform receives identifiers such as the WhatsApp Business Account ID and phone number ID.

Your product should not treat this as a one-time button click. Treat it as a lifecycle:

1. Create or identify the customer and generate a connection link for them.
2. Let the customer complete Meta’s embedded signup.
3. Detect completion through redirect parameters, webhooks, or both.
4. Store the connected phone_number_id and use it for sending, webhooks, workflows, and inbox operations.

What Meta owns

Meta owns the embedded signup UI and the platform checks inside it.

That means Meta controls:

• Facebook or Meta account authentication.
• Business Portfolio selection or creation.
• WhatsApp Business Account selection or creation.
• Phone-number verification or pairing.
• Terms acceptance.
• Permission grants.
• Display-name review, business verification, WABA review, payment prompts, and account restrictions.

Your app can launch the flow and complete the connection, but it cannot bypass Meta’s eligibility checks. If the business has incomplete legal information, unresolved WABA status, a blocked phone number, or billing issues, the connection can still fail or remain pending.

What your SaaS product owns

Your product owns the customer relationship and the data model around the connection.

At minimum, model these records:

The mistake is to store only the final phone number and forget the onboarding state. In production, support questions are usually about the state machine: which business completed signup, what number was selected, whether Meta returned to the app, whether a webhook fired, and whether the WABA is still under review.

Dedicated vs Business App coexistence

There are two common connection modes.

Dedicated Cloud API is API-first. The number moves to the WhatsApp Business Platform and is built for scale. Kapso’s default for platform onboarding is dedicated Cloud API with phone provisioning, while still allowing teams to choose coexistence when the Business App must stay active.

Business App coexistence lets the customer keep using the WhatsApp Business App on their phone while Kapso also receives API events. This is useful for small businesses that need a human app experience and automation at the same time.

Coexistence is convenient, but it has more edge cases. The QR path must appear, old provider links can block onboarding, and Meta-side ownership cleanup can be required when a number was previously connected elsewhere. If your product needs stable high-volume automation, prefer dedicated Cloud API. If your product sells to small businesses that live in the Business App, coexistence can be the right default.

How Kapso connection links work

Kapso connection links are the product-facing version of embedded signup.

You create a Kapso customer, generate a connection link, and send that link to the customer. The customer completes Meta’s flow. Kapso finalizes the connection and gives your product the identifiers it needs.

When you use Kapso-hosted connection links, your product consumes Kapso APIs and webhooks instead of asking the customer for Meta access tokens directly.

curl -X POST https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_link": {
      "success_redirect_url": "https://app.example.com/whatsapp/success",
      "failure_redirect_url": "https://app.example.com/whatsapp/failed",
      "allowed_connection_types": ["dedicated"],
      "provision_phone_number": true
    }
  }'

The link can include:

• Success and failure redirect URLs.
• Language, including English, Spanish, and Portuguese.
• Allowed connection types, such as dedicated, coexistence, or both.
• Phone-number provisioning options.
• Theme colors for the hosted onboarding page.
• Reconnect settings for a previously connected number.

Connection links expire after 30 days, and creating a new active link revokes the previous one for that customer.

If a customer is in the middle of an old connection link when you generate a new one, the old link should no longer be treated as valid in your product. Show the newest link in your UI and make support tooling clear about which connection attempt is active.

Detecting completion

Use both redirect URLs and webhooks when you can.

Redirects are good for user experience. They let your frontend show “connected”, “pending”, or “try again” immediately after the customer returns from Meta.

Webhooks are better for backend truth. A project webhook such as whatsapp.phone_number.created tells your system that Kapso created the connected number record. Use the webhook to persist the phone_number_id, reconcile state, and continue provisioning.

The redirect can be missed if the customer closes the popup. The webhook can arrive after the page has moved on. Together, they make the flow resilient.

The checklist before you ship

Before exposing embedded signup to customers, make sure your product can answer:

• Which customer owns this connection?
• Which connection mode did we offer?
• Did the customer finish Meta signup or abandon it?
• Which phone_number_id was connected?
• Which WABA is used for template management?
• Is the number pending display-name review or WABA review?
• Which webhook events confirm the connection?
• How does the customer reconnect if Meta credentials expire?
• What support data do we show when Meta blocks the flow?

The best “connect WhatsApp” experience feels simple because the product has done the state modeling behind it.

How Kapso fits

Kapso is useful when WhatsApp onboarding is part of your product, not a one-off integration task.

With Kapso Platform, you can map your tenants to Kapso customers, generate WhatsApp connection links, detect completed connections, send from the customer’s number, subscribe to phone-number webhooks, use Workflows, and bring conversations into an inbox when a human needs to take over.

Embedded signup connects the WhatsApp assets. Your product still needs an operating layer around those assets. Kapso provides that layer.