Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt

Use this file to discover all available pages before exploring further.

Bring your own SIM uses Meta embedded signup to connect a phone number you control as a dedicated Cloud API number. For the setup walkthrough, see Connect WhatsApp. Use this page if:
  • Meta does not show the phone number or profile you expected
  • SMS or voice verification fails
  • Meta says the number is already linked somewhere else
  • Kapso says the number already exists
  • Meta says the WABA is unverified or under account review
  • Meta succeeds but Kapso does not show the number as connected

​
Before you retry

Bring your own SIM is for a number that can be dedicated to Cloud API automation. The number should not stay active in the WhatsApp Business App after setup. Before restarting setup, check:
  • you are logged into the correct Facebook account
  • you have admin or sufficient access to the right Meta Business Portfolio
  • the selected Business Portfolio has capacity for another WhatsApp phone number
  • WhatsApp phone numbers does not show unresolved number-status or capacity issues
  • WhatsApp account settings does not show unresolved WABA status, business verification, billing, or payment prompts
  • the number can receive SMS or voice calls during setup
  • the number is not already connected to another Kapso project
  • the number is not still attached to another WABA, previous provider, or WhatsApp Business App account
  • two-step verification is disabled in the source WABA if Meta requires it

​
Common issues

​
Business Portfolio, WABA, or profile is missing

This usually means the wrong Facebook account is logged in, the WABA belongs to another Business Portfolio, or your Meta user does not have enough permissions. What to do:
  1. Confirm you are logged into the Facebook account that owns or manages the business.
  2. Open Meta Business Settings and verify the WABA exists under that business.
  3. Ask a Meta business admin to grant access if you cannot see the business or WABA.
  4. If the portfolio and WABA are correct but your number is missing, choose Create a new WhatsApp Business profile.
  5. Retry Bring your own SIM after access and asset selection are corrected.

​
Meta only shows unrelated WhatsApp Business profiles

Meta may show existing profiles under the selected business account. That list is scoped to the selected Meta business context; it is not a Kapso list of every number you control. What to do:
  1. Do not select an unrelated profile.
  2. Choose Create a new WhatsApp Business profile if Meta offers it.
  3. Continue to phone-number entry and verify the intended number.
  4. If the correct Business Portfolio is missing, restart while logged into a Facebook account with full admin access.

​
Business Portfolio cannot add another phone number

Meta enforces phone-number capacity at the Business Portfolio level. The UI can show a red step, disable Add phone number, or show capacity text such as 1 of 2 added. What to do:
  1. Open WhatsApp Manager.
  2. Review all phone numbers across every WABA under the selected Business Portfolio.
  3. Remove unused numbers if you have Meta admin access.
  4. Complete Meta Business Verification if you need higher phone-number limits.
  5. Retry after Meta shows capacity is available.

​
Kapso says the number already exists

If Kapso says A WhatsApp config with the same display phone number already exists, the number is already connected to another Kapso account or project. What to do:
  1. Disconnect the number from the Kapso account where it is currently connected.
  2. If you own both accounts, contact support with proof that you control the number and both accounts.
  3. Do not keep retrying the same setup. The number cannot be connected twice.

​
Meta says the number is already linked elsewhere

Meta can block setup when the number is still attached to another WABA, previous provider, WhatsApp Business App registration, or stale ownership state. What to do:
  1. Remove the number from old WABAs in WhatsApp Manager where you have admin access.
  2. Disconnect old Business Platform or partner links.
  3. Remove the number from the WhatsApp Business App path if it was used there.
  4. Disable two-step verification in the source WABA if Meta requires it.
  5. Wait a few minutes for Meta cleanup to settle.
  6. Retry through one path only.

​
SMS or voice verification fails

SMS or voice verification is expected for Bring your own SIM. It proves you control the phone line. What to do:
  1. Confirm the phone number and country code.
  2. Use voice call if the number is a landline or cannot receive SMS.
  3. Stop retrying if the resend timer keeps resetting or Meta keeps rejecting the code.
  4. For persistent pending or reset loops, wait 72 hours with no verification, registration, deregistration, SMS, or voice attempts.
  5. Before retrying, remove stale WABA, WhatsApp Business App, and previous-provider attachments where applicable.
  6. After the quiet window, do one clean retry through Kapso.

​
Business profile step is stuck

If Meta stops on a business profile step and Next is disabled, the business profile data may not pass Meta validation. What to do:
  1. Use a real public HTTPS website.
  2. Confirm the website loads in an incognito browser.
  3. Make sure the legal name, address, website, and phone number match the business.
  4. Restart the Meta popup after updating the information.

​
WABA review blocks registration

Every newly created WABA goes through a Meta review before it is fully onboarded. During this period, SMS or voice verification may succeed, but the number can still stay pending while Meta finishes the WABA review. 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. You do not need to keep restarting Bring your own SIM unless support asks you to.

​
WABA, business, or payment restrictions block setup

Meta can block setup or later sending even after the number appears connected. Common causes:
  • WABA is banned, restricted, or under a compliance review
  • Business Portfolio is under compliance review
  • payment eligibility or billing information is incomplete
  • display name is still pending or rejected
  • country restrictions apply
What to do:
  1. Open WhatsApp phone numbers and check for WABA or phone-number warnings.
  2. If Meta points to account-level setup, open WhatsApp account settings and check WABA status, business verification, and billing or payment prompts.
  3. Complete any requested business verification, review, or billing information.
  4. Retry only after Meta clears the restriction.
  5. Send a production test message before treating the number as fully ready.

​
Meta succeeds but Kapso stays pending

Meta can show success while Kapso still cannot finish creating the connected number. What to do:
  1. Confirm Meta showed success.
  2. Confirm whether Kapso still shows setup as pending or failed.
  3. Retry once in a clean browser session if no number was created.
  4. If Meta success repeats but Kapso still cannot create the number, contact support.

​
Still stuck?

Contact support with:
  • your Kapso project URL
  • the phone number you are trying to connect
  • the Business Portfolio and WABA you selected
  • the exact Meta error text
  • screenshots from the Meta popup
  • screenshots from WhatsApp account settings or WhatsApp phone numbers if they show warnings