Create and configure

Setup links let customers connect their WhatsApp Business accounts to your platform. Send a link, customer clicks, logs in with Facebook, and you’re connected.

Quick start

Create a setup link:

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": {
      "success_redirect_url": "https://your-app.com/whatsapp/success",
      "failure_redirect_url": "https://your-app.com/whatsapp/failed",
      "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: {
        success_redirect_url: 'https://your-app.com/whatsapp/success',
        failure_redirect_url: 'https://your-app.com/whatsapp/failed',
        meta_billing_mode: 'partner_managed'
      }
    })
  }
);

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

The response carries the url you send to your customer:

{
  "data": {
    "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "status": "active",
    "url": "https://setup.kapso.ai/s/aB3dEf5g",
    "created_at": "2026-08-01T10:00:00Z",
    "expires_at": "2026-08-31T10:00:00Z",
    "success_redirect_url": "https://your-app.com/whatsapp/success",
    "failure_redirect_url": "https://your-app.com/whatsapp/failed",
    "meta_billing_mode": "partner_managed",
    "allowed_connection_types": ["coexistence", "dedicated"],
    "language": null,
    "theme_config": null,
    "provision_phone_number": false,
    "phone_number_area_code": null,
    "phone_number_country_isos": [],
    "reconnect_phone_number": null,
    "whatsapp_setup_status": "pending",
    "whatsapp_setup_error": null,
    "provisioned_phone_number": null
  }
}

See Connection detection for handling successful connections.

Parameters

Every field is optional. Send only what you want to change from the defaults.

string

Where the customer lands after completing setup. Receives query parameters with setup details.

string

Where the customer lands if setup fails.

string[]

default:"[\"coexistence\", \"dedicated\"]"

Which connection types the customer can pick. Passing a single value auto-selects it and skips the choice.

string

default:"customer_managed"

Who pays Meta’s message fees: customer_managed or partner_managed. See Meta billing policy. Cannot be changed after the link is created.

string

Language for the hosted setup page: en, es, pt, hi, id, or ar. Defaults to the customer’s browser language.

boolean

default:"false"

Provision a phone number for the customer during setup. See Phone number provisioning. Non-US numbers require Twilio credentials.

string[]

default:"[\"US\"]"

Countries the provisioned number can come from, as ISO country codes.

string

Preferred area code for the provisioned number. US only.

object

Brand colors for the hosted setup page. See Theme customization.

string

Scope the link to refresh credentials for a number the customer already has. See Reconnect existing numbers.

Connection types

Customers can connect their WhatsApp in two ways: Coexistence - Keep using WhatsApp Business app alongside API

5 messages/second
App stays active
Good for small businesses

Dedicated - API-only access for automation

Up to 1000 messages/second
No app access
Built for scale

By default the customer chooses. Pass a single value in allowed_connection_types to decide for them:

{
  "setup_link": {
    "allowed_connection_types": ["dedicated"]
  }
}

Meta billing policy

Choose how Meta’s message fees should be paid after the customer connects their WABA:

customer_managed - the customer pays Meta directly. This is the default.
partner_managed - Kapso pays Meta and deducts the cost from the project’s Kapso credits.

{
  "setup_link": {
    "meta_billing_mode": "partner_managed"
  }
}

partner_managed requires Kapso-managed Meta credentials. It is not available on projects using their own Meta app. meta_billing_mode can be set only when creating the link. The response echoes the selected value. Create a new link to change the policy. The hosted setup page does not let the customer change this policy or add billing disclosure. Explain the billing arrangement to your customer before sharing the link. See Meta message billing for the customer-facing differences. Kapso checks WABA-level eligibility after Meta returns the connected account. If Kapso billing cannot be attached, number setup still completes and the project owner sees a retryable warning in Kapso. A completed setup link or meta_billing_mode: "partner_managed" does not confirm that Kapso billing was attached.

Phone number provisioning

Automatically provision a phone number for customers:

{
  "setup_link": {
    "provision_phone_number": true,
    "phone_number_country_isos": ["US", "CL"]
  }
}

Country support

Default Kapso provisioning: ["US"]. See Instant setup
For your own Twilio account, multi-country support, and project-owned pre-verified pools, see Provide local numbers

If the requested country has a ready project pool, setup can use a pre-verified number. If that country has no pool, or the pool is empty, the setup link still works and falls back to live provisioning. When provision_phone_number is enabled, complete Meta’s phone-number step with the Kapso-provided, BSP-provided, or project-pool number shown by the flow, not with Display name only.

Theme customization

Match your brand colors:

{
  "setup_link": {
    "theme_config": {
      "primary_color": "#3b82f6",
      "background_color": "#ffffff",
      "text_color": "#1f2937",
      "muted_text_color": "#64748b",
      "card_color": "#f9fafb",
      "border_color": "#e5e7eb"
    }
  }
}

All colors use hex format (#RRGGBB).

Full example

const setupLink = 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: {
        success_redirect_url: 'https://app.example.com/onboarding/complete',
        failure_redirect_url: 'https://app.example.com/onboarding/error',
        meta_billing_mode: 'partner_managed',
        allowed_connection_types: ['dedicated'],
        provision_phone_number: true,
        phone_number_country_isos: ['US'],
        language: 'es',
        theme_config: {
          primary_color: '#10b981',
          background_color: '#ffffff',
          text_color: '#111827'
        }
      }
    })
  }
);

// Send link to customer
await sendEmail(customer.email, {
  subject: 'Connect your WhatsApp',
  body: `Click here to connect: ${setupLink.data.url}`
});

Getting started

WhatsApp

For your team

Onboard customers

Automations

Quick start

Parameters

Connection types

Meta billing policy

Phone number provisioning

Country support

Theme customization

Full example

​Quick start

​Parameters

​Connection types

​Meta billing policy

​Phone number provisioning

​Country support

​Theme customization

​Full example

Quick start

Parameters

Connection types

Meta billing policy

Phone number provisioning

Country support

Theme customization

Full example