Skip to main content
Kapso surfaces errors from Meta’s WhatsApp Cloud API. Most connection issues are resolved in WhatsApp phone numbers. Use WhatsApp account settings when Meta points to WABA status, business verification, billing, or payment setup.

​
Connection errors

​
”Business account locked”

Your WABA is locked by Meta. Kapso cannot unlock it.
  1. Open WhatsApp Manager
  2. Check Account Overview → Alerts
  3. Click Request review if available
  4. 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.
  1. Open WhatsApp Manager
  2. Complete business verification if pending
  3. Accept any pending terms
  4. Retry connection in Kapso

​
”Review pending” or “Account under review”

Meta reviews every WhatsApp Business Account (WABA) when it is created. This WABA review is separate from Meta Business Portfolio verification, so your business can show as verified while the WABA still blocks phone registration. In Kapso, an issue may appear on the connected number raising this issue. What to do:
  1. Open WhatsApp phone numbers and confirm the number status.
  2. Make sure the Meta Business Portfolio has complete business information, including legal name, address, business phone number, and a public HTTPS website.
  3. Complete any visible Meta-requested action if one appears.
  4. If no action appears, wait for Meta to finish the WABA review.
Kapso saves the WABA review status and shows it in the UI while the number is pending. When Meta sends the WABA review update, Kapso automatically retries phone registration. Kapso cannot approve or clear WABA review directly. If the review remains stuck and Meta shows no customer action, contact support with the WABA ID, phone number ID, exact Meta error text, and screenshots from WhatsApp account settings or WhatsApp phone numbers.

​
Number shows “unavailable”

The connection was lost (similar to WhatsApp Web sessions disconnecting).
  1. Follow the reconnection link in your email
  2. 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.
  1. Open WhatsApp Manager
  2. Find numbers in “Pending” status
  3. Check whether the WABA is still under review or blocked by visible account or phone-number warnings
  4. If the WABA is under review, wait for Meta to finish the review; Kapso will retry registration when Meta sends the review update
  5. If the blocker is not WABA review, delete the pending registration or complete setup, then reconnect in Kapso

​
Cannot add another phone number

Meta Business Portfolios can run out of WhatsApp phone-number capacity. New portfolios usually start with capacity for 2 registered WhatsApp business phone numbers. Meta can later raise this to 20 after business verification or after the portfolio reaches a 2,000 messaging limit. When the portfolio has no capacity left, Meta’s signup flow may not show a clear error. The WhatsApp phone-number step can simply show a red indicator in the left stepper while the form itself has no error message. What to do:
  1. Open WhatsApp phone numbers
  2. Check every WABA under the same Meta Business Portfolio for old, pending, or unused numbers
  3. Remove numbers you no longer use, or ask the Meta Business admin to free capacity
  4. Retry the Kapso connection after Meta shows available phone-number capacity
Kapso cannot increase this Meta-side limit directly. If the portfolio should have capacity but Meta still blocks the flow with only the red step indicator, contact Meta Business Support or Kapso support with screenshots from the signup flow and WhatsApp Manager.

​
Sending errors

​
Template fails because of payment issues

If an approved template fails with There is an issue with the payment method, Payment method required, or a payment eligibility error, Meta is blocking the send because the WABA billing setup is incomplete. Follow Payment issues to check the Meta payment method, Billing Hub, business information, and WABA approval status.

​
”invalid url” for template header image

  • 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

​
”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

​
Meta access tokens

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.

​
Conversation tags/labels

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:

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