Onboard your customers to WhatsApp
Enable your customers to connect their WhatsApp Business Account to Kapso using secure setup links or the embedded signup flow
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:
The external_customer_id
should match your internal customer identifier for easy reference.
Step 2: Generate a setup link
Create a secure, time-limited setup link for your customer with optional redirect URLs:
The response will include:
The redirect URLs are optional. If not provided, users will see a default success or error page on Kapso after setup completion.
Step 3: Share the setup link
Send the setup URL to your customer via:
- 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
Failure redirect
Error codes include:
facebook_auth_failed
- Facebook login was cancelled or failedphone_verification_failed
- Phone number verification failedwaba_limit_reached
- WhatsApp Business Account limit exceededtoken_exchange_failed
- OAuth token exchange failedlink_expired
- Setup link has expiredlink_revoked
- Setup link was revokedalready_used
- Setup link was already usedunknown_error
- An unexpected error occurred
What happens during onboarding
When customers click the setup link, they’ll experience:
- Authentication: Log in with their Facebook account
- Business setup: Create or select their Business Manager
- WhatsApp configuration: Set up their WhatsApp Business Account
- Phone verification: Register and verify their business phone number
- 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
Managing setup links
List all setup links
Revoke a setup link
Creating a new setup link automatically revokes the previous one. Links are also automatically marked as “used” after successful completion.
Troubleshooting
Setup link shows as expired
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:
- Ensure pop-up blockers are disabled
- Try a different browser
- Clear Facebook cookies and cache
WhatsApp Business Account creation fails
Error: Unable to create WhatsApp Business Account
Solution:
- Verify the customer has admin access to their Business Manager
- Check if they’ve reached the WABA limit (5 per Business Manager)
- 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