Embed WhatsApp onboarding

Choose the path that matches Messages processed by in your Multi-partner Solution.

Messages processed by	Browser integration	Who completes onboarding
Kapso	`@kapso/sdk` with a Kapso setup link	Kapso
Your infrastructure	Meta JavaScript SDK with your Solution ID	Your backend; Kapso handles eligible managed funding

Kapso runs messaging

Use @kapso/sdk to open onboarding from your product. Your backend creates the setup link; the browser receives only its token, never your Kapso API key.

@kapso/sdk requires an active Kapso Multi-partner Solution. It is not a generic embedded signup SDK and does not work with standalone custom Meta apps.

Requirements

an active Multi-partner Solution with Messages processed by: Kapso
the browser origin in the setup link’s allowed_origins
the same HTTPS domain added in Meta’s Facebook Login for Business settings

The setup link must allow exactly one connection type: dedicated or coexistence. Create separate setup links if your product offers both paths.

Install the SDK

npm install @kapso/sdk

yarn add @kapso/sdk

pnpm add @kapso/sdk

Create a setup link on your backend

Keep your Kapso API key on the server. Create one setup link for the customer and specify every browser origin that may launch it.

curl -X POST https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_link": {
      "allowed_origins": ["https://app.example.com"],
      "allowed_connection_types": ["dedicated"],
      "meta_billing_mode": "partner_managed"
    }
  }'

const res = await fetch(
  `https://api.kapso.ai/platform/v1/customers/${customerId}/setup_links`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      setup_link: {
        allowed_origins: ['https://app.example.com'],
        allowed_connection_types: ['dedicated'],
        meta_billing_mode: 'partner_managed'
      }
    })
  }
);

const { data } = await res.json();

Return only data.token to your frontend. Do not expose your Kapso API key.

Connect from the browser

import { createWhatsAppOnboarding } from '@kapso/sdk';

const whatsapp = await createWhatsAppOnboarding({ token: setupLinkToken });

connectButton.onclick = async () => {
  const connection = await whatsapp.connect();
  onConnected(connection);
};

The resolved connection includes:

type WhatsAppConnection = {
  whatsappConfigId: string;
  wabaId: string;
  phoneNumberId: string;
};

The SDK validates the token and browser origin, loads the Meta JavaScript SDK, runs embedded signup with your Multi-partner Solution, and resolves once Kapso confirms the connection.

Configure the setup path

The setup link controls the customer experience:

allowed_connection_types: ["dedicated"] — API-only WhatsApp number
allowed_connection_types: ["coexistence"] — keep using WhatsApp Business App
provision_phone_number: true — use a Kapso-provided or project-pool number
meta_billing_mode: "partner_managed" — use Kapso credits for Meta fees

Set these on the server when you create the link. The browser receives only the setup token.

Handle cancellation and errors

Catch SDK initialization failures separately from connection failures. Keep connect() inside the button’s click handler so the browser allows Meta’s popup.

import {
  createWhatsAppOnboarding,
  WhatsAppOnboardingError,
} from '@kapso/sdk';

connectButton.disabled = true;

try {
  const whatsapp = await createWhatsAppOnboarding({ token: setupLinkToken });
  connectButton.disabled = false;

  connectButton.onclick = async () => {
    connectButton.disabled = true;

    try {
      onConnected(await whatsapp.connect());
    } catch (error) {
      if (!(error instanceof WhatsAppOnboardingError && error.code === 'user_cancelled')) {
        showConnectionError();
      }
    } finally {
      connectButton.disabled = false;
    }
  };
} catch {
  showConnectionError();
}

Call whatsapp.destroy() if your application removes the onboarding component before setup completes.

Confirm connection on your backend

Use the browser result for immediate UI feedback. For server-side reliability, subscribe to Kapso project webhooks and listen for whatsapp.phone_number.created. See Detect connection and Webhooks.

You run messaging

Use the Meta JavaScript SDK and your own backend. This path does not use @kapso/sdk, a Kapso setup link, or Kapso’s onboarding endpoints. You own registration, messaging, and message webhooks; Kapso provides managed billing.

Prepare your Meta app

Activate a Multi-partner Solution with Messages processed by: Your infrastructure and App with messaging permission: Your Meta app.
Copy the Meta solution ID from Tenants > Multi-partner solution. This is not the Meta App ID or a Kapso UUID.
Create a Facebook Login for Business configuration for your Tech Provider app, using WhatsApp Embedded Signup v4 and the products you need.
Add your HTTPS domain and OAuth redirect URIs in Meta’s login settings. Kapso setup-link allowed_origins does not apply to this path.
Configure your webhook endpoint and subscribe your Meta app to account_update and messages.

Use your own app’s IDs below. Never include your app secret or access tokens in browser code. See Meta’s implementation guide for the app configuration. If you already have Embedded Signup, add extras.setup.solutionID to your existing FB.login options. Keep the SDK initialization and flow options appropriate for your configuration. For a new v4 integration, this example initializes Meta once and enables the button only after FB.init completes:

<button id="connect-whatsapp" disabled>Connect WhatsApp</button>
<p id="whatsapp-status" role="status"></p>

<script>
  const connectButton = document.getElementById('connect-whatsapp');
  const signupStatus = document.getElementById('whatsapp-status');

  window.fbAsyncInit = function () {
    FB.init({
      appId: 'YOUR_TECH_PROVIDER_APP_ID',
      version: 'v25.0',
      autoLogAppEvents: false,
      xfbml: false
    });
    connectButton.disabled = false;
  };

  connectButton.onclick = function () {
    connectButton.disabled = true;
    signupStatus.textContent = 'Opening Meta…';

    FB.login((response) => {
      const code = response.authResponse?.code;
      if (!code) {
        signupStatus.textContent = 'Setup was not completed.';
        connectButton.disabled = false;
        return;
      }

      void completeOnboarding(code);
    }, {
      config_id: 'YOUR_EMBEDDED_SIGNUP_CONFIG_ID',
      response_type: 'code',
      override_default_response_type: true,
      extras: {
        setup: {
          solutionID: 'YOUR_META_SOLUTION_ID'
        }
      }
    });
  };

  async function completeOnboarding(code) {
    signupStatus.textContent = 'Completing setup…';

    try {
      // Your endpoint, not a Kapso API. Implement the backend steps below.
      const response = await fetch('/api/whatsapp/onboarding/complete', {
        method: 'POST',
        credentials: 'same-origin',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code })
      });
      if (!response.ok) throw new Error('Onboarding failed');

      signupStatus.textContent = 'Connected. Check managed funding in Kapso before sending paid messages.';
    } catch {
      signupStatus.textContent = 'Could not complete setup. Check your backend before retrying.';
    } finally {
      connectButton.disabled = false;
    }
  }
</script>
<script async defer crossorigin="anonymous" src="https://connect.facebook.net/en_US/sdk.js"></script>

solutionID is case-sensitive and belongs inside extras.setup, not at the top level. Keep it as a string. The Solution ID links the customer’s authorization to both partners. See Meta’s Multi-partner Solution instructions. If you offer multiple solutions, select the correct App ID, configuration ID, and Solution ID for the customer before enabling the button. Store that expected context with the onboarding attempt on your backend.

Complete onboarding on your backend

The example’s /api/whatsapp/onboarding/complete is an endpoint in your application. Protect it with your normal authentication and CSRF controls; adapt the request headers to your framework. Bind the attempt to the signed-in customer.

Exchange code through Meta’s GET /oauth/access_token, using your App ID and app secret. Store the returned business token securely on your server; do not log it or return it to the browser.
Resolve the authorized WABA and phone number using that token. If multiple assets are available, confirm the customer’s selection rather than choosing the first result. You can also collect IDs through Meta’s WA_EMBEDDED_SIGNUP browser event: validate the event origin and verify asset access server-side. Browser-supplied IDs are not proof of ownership or funding.
Subscribe your app to the customer’s WABA with POST /{WABA_ID}/subscribed_apps so your backend receives message webhooks.
Register the phone number with POST /{PHONE_NUMBER_ID}/register when required by the selected flow. The example targets the standard Cloud API flow; follow Meta’s separate requirements for coexistence, migrations, or WABA-only signup.
Persist the connection in your system. Return success only after the required backend setup completes.

Use Meta’s Tech Provider onboarding guide for the requests. For Kapso-managed billing, use the funding confirmation below instead of asking the customer to add a Meta payment method.

Confirm managed funding in Kapso

Meta notifies Kapso through account_update when the customer joins the solution. Kapso detects the WABA and attempts to fund it automatically, subject to eligibility and your project’s prepaid balance. You do not need to send Kapso the customer’s authorization code or business token. Open Tenants > Multi-partner solution, find the WABA, and confirm that managed funding is verified before sending paid messages. A successful signup callback or a detected WABA alone does not confirm funding. If the account shows Needs attention, resolve the displayed issue first. External onboarding does not create a Kapso WhatsApp configuration or emit the hosted path’s whatsapp.phone_number.created event. Your own backend tracks connection completion; the Kapso account table tracks funding and aggregate usage. If the WABA does not appear, check that signup used the exact active Solution ID and the correct Meta app. If those match, contact Kapso with the Solution ID, WABA ID, and signup time. Do not send secrets or access tokens. Once funded, keep sending through your own Meta integration. Kapso checks Pricing Analytics about every five minutes; usage can arrive later. Kapso cannot block sends made through your infrastructure, so keep enough balance for usage between checks. See managed billing and beta limitations.

Getting started

WhatsApp

For your team

Onboard customers

Automations

Migrate to Kapso

Kapso runs messaging

Requirements

Install the SDK

Create a setup link on your backend

Connect from the browser

Configure the setup path

Handle cancellation and errors

Confirm connection on your backend

You run messaging

Prepare your Meta app

Complete onboarding on your backend

Confirm managed funding in Kapso

​Kapso runs messaging

​Requirements

​Install the SDK

​Create a setup link on your backend

​Connect from the browser

​Configure the setup path

​Handle cancellation and errors

​Confirm connection on your backend

​You run messaging

​Prepare your Meta app

​Launch Embedded Signup

​Complete onboarding on your backend

​Confirm managed funding in Kapso

Kapso runs messaging

Requirements

Install the SDK

Create a setup link on your backend

Connect from the browser

Configure the setup path

Handle cancellation and errors

Confirm connection on your backend

You run messaging

Prepare your Meta app

Launch Embedded Signup

Complete onboarding on your backend

Confirm managed funding in Kapso