> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create and configure
> Create a setup link and configure everything your customer will see
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:
```bash cURL theme={null}
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"
}
}'
```
```javascript JavaScript theme={null}
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:
```json theme={null}
{
"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](/docs/platform/setup-links/detect-connection) for handling successful connections.
## Parameters
Every field is optional. Send only what you want to change from the defaults.
Where the customer lands after completing setup. Receives query parameters with setup details.
Where the customer lands if setup fails.
Which [connection types](#connection-types) the customer can pick. Passing a single value auto-selects it and skips the choice.
Who pays Meta's message fees: `customer_managed` or `partner_managed`. See [Meta billing policy](#meta-billing-policy). Cannot be changed after the link is created.
Language for the hosted setup page: `en`, `es`, `pt`, `hi`, `id`, or `ar`. Defaults to the customer's browser language.
Provision a phone number for the customer during setup. See [Phone number provisioning](#phone-number-provisioning). Non-US numbers require Twilio credentials.
Countries the provisioned number can come from, as ISO country codes.
Preferred area code for the provisioned number. US only.
Brand colors for the hosted setup page. See [Theme customization](#theme-customization).
Scope the link to refresh credentials for a number the customer already has. See [Reconnect existing numbers](#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:
```json theme={null}
{
"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.
```json theme={null}
{
"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](/docs/whatsapp/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:
```json theme={null}
{
"setup_link": {
"provision_phone_number": true,
"phone_number_country_isos": ["US", "CL"]
}
}
```
### Country support
* Default Kapso provisioning: `["US"]`. See [Instant setup](/docs/platform/phone-numbers/instant-setup)
* For your own Twilio account, multi-country support, and project-owned pre-verified pools, see [Provide local numbers](/docs/platform/phone-numbers/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](/docs/how-to/whatsapp/connect-whatsapp#why-to-avoid-display-name-only).
## Theme customization
Match your brand colors:
```json theme={null}
{
"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
```javascript theme={null}
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}`
});
```