This guide walks you through the process of onboarding your customers to WhatsApp, allowing them to connect their WhatsApp Business Account to Kapso without sharing sensitive credentials.
WhatsApp onboarding with Kapso transforms a complex multi-day process into a seamless 5-minute experience. Customers can connect their WhatsApp Business Account directly through your application without leaving your interface.

​
API-based onboarding

This method is ideal for automated onboarding flows or when you want to programmatically create setup links for your customers.

​
Step 1: Create a customer

First, create a customer record if you haven’t already: 
curl -X POST https://app.kapso.ai/api/v1/customers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Acme Corporation",
      "external_customer_id": "CUS-12345"
    }
  }'
The external_customer_id should match your internal customer identifier for easy reference.
Create a secure, time-limited setup link for your customer. The simplest version: 
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"
Or with full customization: 
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",
      "allowed_connection_types": ["coexistence", "dedicated"],
      "theme_config": {
        "primary_color": "#3b82f6",
        "background_color": "#ffffff"
      }
    }
  }'
The response will include: 
{
  "data": {
    "id": "link-123abc",
    "status": "active",
    "expires_at": "2024-02-15T10:00:00Z",
    "url": "https://app.kapso.ai/whatsapp/setup/aBcD123...",
    "success_redirect_url": "https://your-app.com/whatsapp/success",
    "failure_redirect_url": "https://your-app.com/whatsapp/failed"
  }
}
  • success_redirect_url (optional): Where to redirect after successful setup
  • failure_redirect_url (optional): Where to redirect after failed setup
  • allowed_connection_types (optional): Array of connection types to show. Options: ["coexistence", "dedicated"]
  • theme_config (optional): Customize the setup page appearance with colors
All parameters are optional. The system uses sensible defaults when parameters are not provided.
Share the setup URL to your customer via:
  • UI / your app
  • Email
  • In-app notification
  • Support ticket
  • SMS
Setup links expire after 30 days and can only be used once. Creating a new link automatically revokes any existing active links for that customer.

​
Handling redirect responses

When setup completes, customers are redirected to your specified URLs with additional parameters:

​
Success redirect

https://your-app.com/whatsapp/success?setup_link_id={link_id}&status=completed

​
Failure redirect

https://your-app.com/whatsapp/failed?setup_link_id={link_id}&error_code={code}
Error codes include:
  • facebook_auth_failed - Facebook login was cancelled or failed
  • phone_verification_failed - Phone number verification failed
  • waba_limit_reached - WhatsApp Business Account limit exceeded
  • token_exchange_failed - OAuth token exchange failed
  • link_expired - Setup link has expired
  • link_revoked - Setup link was revoked
  • already_used - Setup link was already used
  • unknown_error - An unexpected error occurred

​
What happens during onboarding

When customers click the setup link, they’ll experience:
  1. Authentication: Log in with their Facebook account
  2. Business setup: Create or select their Business Manager
  3. WhatsApp configuration: Set up their WhatsApp Business Account
  4. Phone verification: Register and verify their business phone number
  5. Automatic connection: Kapso automatically configures the integration
The entire process typically takes less than 5 minutes.

​
Customization options

​
Connection type control

Control which connection options your customers see by specifying allowed_connection_types: 
{
  "setup_link": {
    "allowed_connection_types": ["coexistence"]  // Show only coexistence option
  }
}
Options:
  • ["coexistence"] - Show only coexistence option
  • ["dedicated"] - Show only dedicated option
  • ["coexistence", "dedicated"] - Show both options (default)

​
Theme customization

Brand the setup page to match your application: 
{
  "setup_link": {
    "theme_config": {
      "primary_color": "#3b82f6",
      "background_color": "#ffffff", 
      "text_color": "#1f2937",
      "card_color": "#f9fafb",
      "border_color": "#e5e7eb"
    }
  }
}
Available theme colors:
  • primary_color - Button and accent color
  • background_color - Page background
  • text_color - Main text color
  • muted_text_color - Secondary text color
  • card_color - Card backgrounds
  • muted_color - Muted backgrounds
  • border_color - Border color
  • destructive_color - Error color
  • primary_foreground_color - Button text color
  • secondary_color - Secondary button color
  • secondary_foreground_color - Secondary button text color
  • destructive_foreground_color - Error text color

​
Connection types

During setup, customers can choose between two connection types:

​
Coexistence

  • Rate limit: 5 messages per second
  • Use case: Small businesses using WhatsApp Business App
  • Benefit: Continue using the mobile app alongside API integration

​
Dedicated (Cloud API only)

  • Rate limit: Up to 1000 messages per second
  • Use case: High-volume messaging needs
  • Benefit: Full API features and scalability
curl -X GET https://app.kapso.ai/api/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: YOUR_API_KEY"
Creating a new setup link automatically revokes the previous one. Links are also automatically marked as “used” after successful completion.

​
Troubleshooting

Error: Customer receives an “expired link” error
Solution: Generate a new setup link using the API endpoint above

​
Customer can’t complete Facebook login

Error: Facebook login fails or hangs
Solution:
  1. Ensure pop-up blockers are disabled
  2. Try a different browser
  3. Clear Facebook cookies and cache

​
WhatsApp Business Account creation fails

Error: Unable to create WhatsApp Business Account
Solution:
  1. Verify the customer has admin access to their Business Manager
  2. Check if they’ve reached the WABA limit (5 per Business Manager)
  3. Ensure the phone number isn’t already registered with another WABA

​
Next steps

Configure webhooks

Set up webhooks to receive WhatsApp messages and status updates

Send your first message

Learn how to send messages through the WhatsApp API

Create message templates

Design and submit message templates for approval

Connect to agents

Link WhatsApp configs to AI agents for automated conversations