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.

Method 1: 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 with optional 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"
    }
  }'

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"
  }
}

The redirect URLs are optional. If not provided, users will see a default success or error page on Kapso after setup completion.

Send the setup URL to your customer via:

  • 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.

Connection types

During setup, customers can choose between two connection types:

Business App (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