Kapso surfaces errors from Meta’s WhatsApp Cloud API. Most issues are resolved in WhatsApp Manager.
Connection errors
”Business account locked”
Your WABA is locked by Meta. Kapso cannot unlock it.
- Open WhatsApp Manager
- Check Account Overview → Alerts
- Click Request review if available
- Ensure your business has: accessible website, privacy policy, terms of service
Once Meta restores access, messages in Kapso will deliver automatically.
”Invalid account linking” or “Request code error”
Your WABA is pending approval or has incomplete verification.
- Open WhatsApp Manager
- Complete business verification if pending
- Accept any pending terms
- Retry connection in Kapso
Number shows “unavailable”
The connection was lost (similar to WhatsApp Web sessions disconnecting).
- Follow the reconnection link in your email
- Or reconnect from Connected numbers in Kapso
Once reconnected, sending and receiving resumes automatically.
Number stuck in “Pending” state
A pending number registration can block new connections.
- Open WhatsApp Manager
- Find numbers in “Pending” status
- Delete the pending registration or complete setup
- Retry connection in Kapso
Sending errors
- Verify the URL is publicly accessible (test in incognito browser)
- Check for leading/trailing whitespace in the URL
- Ensure no authentication is required to access the image
A space at the start of the URL (e.g., https://...) is a common cause when importing from CSV.
”Phone number is required”
The to field is missing in your API request. Ensure you’re including the recipient phone number in E.164 format.
Messages not delivering
Check the message status in Kapso:
- Sent — delivered to Meta
- Delivered — reached the recipient’s device
- Read — recipient opened the message
- Failed — check the error reason
For failed messages, the error typically comes from Meta. Common causes:
- Recipient blocked your number
- Invalid phone number format
- 24-hour window expired (use a template instead)
Unsupported features
Kapso manages WhatsApp API credentials internally. You don’t receive a raw Meta access token when connecting.
If you need tokens for other Meta APIs (Conversions API, Ads API), generate them separately in Meta Business Settings.
Tagging conversations via API is not currently supported. Use the inbox UI to organize conversations manually.
Blocking numbers
There’s no API to block specific numbers from triggering webhooks or flows. Handle filtering in your webhook receiver:
const BLOCKED = new Set(['15551234567']);
app.post('/webhook', (req, res) => {
const phone = req.body.data.message.from;
if (BLOCKED.has(phone)) {
return res.status(200).send('Blocked');
}
// Process normally
});
Third-party WhatsApp providers
Kapso connects directly to Meta’s WhatsApp Cloud API. Numbers from other Business Solution Providers (360dialog, Twilio, MessageBird, etc.) cannot be connected.
To use Kapso, migrate your number to a direct Meta WABA via WhatsApp Manager. 
