Skip to main content
Setup links are how your customers connect their WhatsApp. Customize them to match your brand. 
curl -X POST https://app.kapso.ai/api/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY"
Creates a link with default settings. Customer sees both connection options.

​
With redirect URLs

curl -X POST https://app.kapso.ai/api/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"
    }
  }'

​
Success redirect

After successful setup, customer goes to: 
https://your-app.com/whatsapp/success?setup_link_id={link_id}&status=completed&whatsapp_config_id={config_id}

​
Failure redirect

If setup fails: 
https://your-app.com/whatsapp/failed?setup_link_id={link_id}&error_code={code}
Error codes:
  • facebook_auth_failed - Facebook login cancelled
  • phone_verification_failed - Phone verification failed
  • waba_limit_reached - Too many WhatsApp accounts
  • token_exchange_failed - OAuth failed
  • link_expired - Link expired (30 days)
  • already_used - Link already used

​
Connection type control

​
Show both options (default)

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

​
Coexistence only

For customers using WhatsApp Business app: 
{
  "setup_link": {
    "allowed_connection_types": ["coexistence"]
  }
}

​
Dedicated only

For API-only automation: 
{
  "setup_link": {
    "allowed_connection_types": ["dedicated"]
  }
}
When you provide one option, it auto-selects.

​
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).

​
Phone number provisioning

Automatically provision a phone number for customers: 
{
  "setup_link": {
    "provision_phone_number": true,
    "phone_number_country_isos": ["US"]
  }
}

​
Country support

  • Default: ["US"] - US phone numbers only
  • Non-US countries require custom Twilio credentials (contact sales)
{
  "setup_link": {
    "provision_phone_number": true,
    "phone_number_country_isos": ["US", "CL"]
  }
}

​
Full example

const setupLink = await fetch(
  `https://app.kapso.ai/api/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',
        allowed_connection_types: ['dedicated'],
        provision_phone_number: true,
        phone_number_country_isos: ['US'],
        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}`
});

curl https://app.kapso.ai/api/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY"

​
Automatic revocation

Creating a new link revokes the previous one. Only one active link per customer.

​
Expiration

Links expire after 30 days. Check the expires_at field.
⌘I