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

# Connect WhatsApp

> Connect your WhatsApp Business account to Kapso

Connecting WhatsApp takes about 5 minutes using Meta's embedded signup flow.

## Before you connect

Meta controls the login, business selection, and approval checks inside embedded signup. Before you start, make sure you have a Facebook account.

During the flow you can create a Meta Business Portfolio and WhatsApp Business Account (WABA) if you need. If you already have these created, make sure you have:

* access to the correct Meta Business Portfolio
* access to the WhatsApp Business Account (WABA)
* complete business information in Meta, including legal name, address, business phone number, and a public HTTPS website
* no unresolved number-status or capacity issues in [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers)
* no unresolved WABA status, business verification, billing, or payment prompts in [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account)
* capacity in the selected Business Portfolio for another WhatsApp phone number

Connecting a number does not bypass Meta requirements. Display-name review, business verification, WABA review, payment eligibility, template review, and country or account restrictions can still block production sending after the number is connected.

## Connection options

| Option | Best for | Requirements |
| - | - | - |
| [**Instant setup**](#instant-setup-digital-number) | Get started immediately | Facebook account |
| [**WhatsApp Business App**](#whatsapp-business-app) | Keep using the app alongside Kapso | Active WhatsApp Business App number and phone access |
| [**Bring your own SIM**](#bring-your-own-sim) | Use your own phone number | Dedicated SIM card |

## Instant setup (digital number)

Get a pre-verified US phone number without SMS verification.

Before using this option:

* use a Meta Business Portfolio that can add another WhatsApp phone number
* choose one of the pre-verified numbers inside Meta (Meta may call it a Kapso-provided or BSP-provided number)
* watch the pre-signup guidance in Kapso if it appears, because it shows which Meta phone-number option to choose

If Meta does not show a pre-verified number, asks for SMS verification, or blocks setup, see [Instant setup troubleshooting](https://docs.kapso.ai/docs/how-to/whatsapp/instant-setup-troubleshooting.md).

In Kapso:

1. Go to **Connected numbers** → **Connect new number**
2. Select **Instant setup**
3. Confirm the instruction that you should choose a pre-verified number in Meta
4. Watch the pre-signup guidance if Kapso shows it
5. Click through to open Meta embedded signup

In Meta embedded signup:

1. Log in with the Facebook account that has access to your business. On **Seamlessly connect your account to Kapso**, review what Kapso will be able to do and click **Continue**.

   ![Meta embedded signup asks you to continue connecting the account to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-continue.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=4fd2c84ee90c52b78e9e0affe7a852de)

2. On **Add your WhatsApp phone number**, open the **Phone number** dropdown. It starts on **Enter a new phone number**.

   ![Meta shows the Add your WhatsApp phone number screen with the Phone number dropdown.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-number-option.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=e47c50c71e650dfc2f29b47d2bdb1187)

3. Select one of the pre-verified numbers in the list. They show a briefcase icon and a **Verified** badge. Do not choose **Use a display name with a virtual number instead**, and do not choose **Enter a new phone number**.

   ![Meta lists pre-verified numbers with a Verified badge under the display name option.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-bsp-number.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=cb202e9233040e9a09543ed39d97ff79)

4. Confirm that the number you picked is shown in the **Phone number** field, then click **Next**.

   ![Meta shows the selected pre-verified number and an enabled Next button.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-selected-number.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=2ad523d883f5a59508056c3b02dc923e)

5. On **Select the business assets to share with Kapso**, choose the **Business portfolio** for the business you want to connect.

   ![Meta asks you to select the business portfolio to share with Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-business-portfolio.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=3f86d39d482ccc7120e0ff225a06d455)

6. In **WhatsApp Business account**, choose an existing account or **Create a WhatsApp Business account**, then click **Next**.

   ![Meta asks you to select or create the WhatsApp Business account to share with Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-assets.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=a9416b8a623818d1809f9c56a59264ab)

7. On **Review what you'll share with Kapso**, review the requested access and click **Confirm**. Meta shows **Connecting your account** for a few moments.

   ![Meta shows the permissions Kapso will receive for the selected business and WhatsApp account.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-review-permissions.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=30e6d8bef9dd9af9930f98dbe0137d39)

8. When Meta shows **Your account is connected to Kapso**, click **Finish**. This final step sends you back to Kapso so the connection can be completed.

   ![Meta confirms that the account is connected to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/instant-setup-connected.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=6353fcebe65f6509916a6800900fd378)

After Meta returns you to Kapso, Kapso finalizes the connection and shows the phone number as connected.

![Kapso shows the phone number as connected after Meta returns to the app.](https://mintcdn.com/kapso/42TG2gfzA5DLrWPX/images/connect-whatsapp/instant-setup-kapso-connected.png?fit=max\&auto=format\&n=42TG2gfzA5DLrWPX\&q=85\&s=06eae53fc640de473f24556da72f8525)

If the WABA is still under Meta review, the number may stay pending until Meta finishes that review. Kapso shows the saved WABA status in the UI and automatically retries registration when Meta sends the review update. While waiting, make sure the Meta Business Portfolio has complete business information, including legal name, address, business phone number, and a public HTTPS website.

The small deposit goes directly to your project credits. Available on all plans.

If you need local numbers, your own Twilio account, or project-owned reusable pools, see [Provide local numbers](https://docs.kapso.ai/docs/platform/phone-numbers/provide-local-numbers.md).

If the flow asks for SMS verification instead of instant setup, cancel and retry. If it persists, see [Instant setup troubleshooting](https://docs.kapso.ai/docs/how-to/whatsapp/instant-setup-troubleshooting.md).

## WhatsApp Business App

Keep using the WhatsApp Business app on your phone alongside Kapso.

Before using this option:

* make sure the number is active in the WhatsApp Business App, not the personal WhatsApp app
* update the WhatsApp Business App and keep the phone nearby with a working camera
* for a number linked to another provider, follow the [coexistence recovery steps](https://docs.kapso.ai/docs/how-to/whatsapp/coexistence-troubleshooting.md#number-is-already-linked-to-another-account-or-provider), including credit-line verification
* complete Business App pairing when prompted; if Meta asks for SMS or voice code verification instead, stop and send support screenshots of the full flow

If the number does not connect, your WABA does not appear, or Meta sends you to the wrong onboarding path, see [Coexistence troubleshooting](https://docs.kapso.ai/docs/how-to/whatsapp/coexistence-troubleshooting.md).

In Kapso:

1. Go to **Connected numbers** → **Connect new number**
2. Select **WhatsApp Business App**
3. Click through to open Meta embedded signup

In the current Meta flow you enter your Business App number first. Meta detects that the number is active in the WhatsApp Business App, shows its profile, and then asks you to pair the app with a QR code. There is no separate **Connect a WhatsApp Business App** option to pick. Meta may show the partner name as **Kapso** or **Kapso Connect**. Both are Kapso.

In Meta embedded signup:

1. Log in with the Facebook account that has access to your business. On **Seamlessly connect your account to Kapso**, review what Kapso will be able to do and click **Continue**.

   ![Meta embedded signup asks you to continue connecting the account to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-continue.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=27299d1b7a82e0b6e914321d92146cbd)

2. On **Add your WhatsApp phone number**, keep **Enter a new phone number** selected. Select the country code, enter the phone number that is already active in your WhatsApp Business App, and click **Next**.

   ![Meta asks for the WhatsApp Business App phone number with the country code.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-number.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=4819498dec3ca320c292386ebeea0aae)

3. On **Verify your account details**, check that the profile name, number, and website match your WhatsApp Business App, then click **Next**. If the details are wrong, click **Back** and fix the phone number.

   ![Meta shows the WhatsApp Business App profile linked to the number.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-verify-details.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=6d00703d3c5930e670ca1bab6174d0dc)

4. On **Select the business assets to share with Kapso**, choose the **Business portfolio** for the business that owns this WhatsApp number and click **Next**.

   ![Meta asks you to select the business portfolio to share with Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-business-portfolio.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=60cc2ef7706eae66bf57b90aff0bb113)

5. On **Import contacts and chat history**, Meta shows a QR code. Keep the browser window open and pick up your phone.

   ![Meta shows the QR code to scan with the WhatsApp Business App.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-meta-qr.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=601b86cba4186574e8e1dac862835226)

6. Open the WhatsApp Business App and tap the camera icon in **Chats**.

   ![The WhatsApp Business App Chats screen with the camera icon at the top.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-chats.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=2323dce3496fbbc20da3bf1ce18f0c1e)

7. Point the camera at the QR code in the browser. When the app asks **Connect to Business Platform?**, tap **Continue**.

   ![The WhatsApp Business App camera scans the QR code on the Meta screen.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-qr-scan.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=6c2d4c36063b852c8347e7b69de7265f)

   ![The WhatsApp Business App asks you to confirm the connection to the Business Platform.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-connect-prompt.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=5bb33d72fe9d9c7cbc1c6a9ac35baa24)

8. On **Connect to the Business Platform**, review the information and tap **Connect to the Business Platform**.

   ![The WhatsApp Business App shows the Connect to the Business Platform screen.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-connect-platform.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=a016ffc5469bf5562c5cc10b18c16d9d)

9. On **Share chat history**, choose **Share all chats** or **Don't share chats**, then tap **Confirm**. You cannot change this decision later. The app may ask for Face ID or your passcode.

   ![The WhatsApp Business App asks whether to share chat history.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-share-history.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=8a0feeb9633236287f715666e4b72962)

10. Scan the QR code until the app shows **Connecting your account**. If you can't scan, tap **Enter Access Code Instead** and use the code from the Meta screen.

    ![The WhatsApp Business App asks you to scan the QR code from the Business Platform.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-scan-qr.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=1efe38a3d990b605e0ed2635c350f548)

11. When the phone shows **Connected platform** with Kapso listed, go back to the browser.

    ![The WhatsApp Business App shows Kapso as the connected platform.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-phone-connected.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=f6181fc3843b0017ef29731b0639441b)

12. On **Confirm or edit your WhatsApp Business account**, confirm the WhatsApp Business account name, select the **Time zone**, and click **Next**.

    ![Meta asks you to confirm the WhatsApp Business account name and time zone.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-confirm-account.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=8facc6ea8c83f4cdb211ca8848647447)

13. On **Review what you'll share with Kapso**, review the requested access and click **Confirm**.

    ![Meta shows the permissions Kapso will receive for the selected business and WhatsApp account.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-review-permissions.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=3f8911111a617865915662d50c7398f2)

14. When Meta shows **Your account is connected to Kapso**, click **Finish**. This final step sends you back to Kapso so the connection can be completed.

    ![Meta confirms that the account is connected to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/coexistence-meta-connected.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=f15d97b88be83f8b555d089e53156499)

After Meta returns you to Kapso, Kapso finalizes the connection and starts syncing the coexistence number. Messages can then appear in both the WhatsApp Business App and Kapso.

![Kapso shows the WhatsApp Business App number as connected after Meta returns to the app.](https://mintcdn.com/kapso/42TG2gfzA5DLrWPX/images/connect-whatsapp/coexistence-kapso-connected.png?fit=max\&auto=format\&n=42TG2gfzA5DLrWPX\&q=85\&s=8328796dc37b356236abd0d5ffc360ee)

If Meta asks for SMS or voice code verification instead of Business App pairing, stop and send support screenshots or a recording of the full flow. Entering the number first is normal in the current flow; it does not by itself mean you chose the wrong connection mode.

## Bring your own SIM

Use a phone number you already control as a dedicated Cloud API number.

This path is for a number that can move fully to Kapso's API connection. It is not for keeping the same number active in the WhatsApp Business App.

Before using this option:

* keep the SIM, phone line, or landline available during setup
* use a number you can verify by SMS or voice call
* make sure the number is not already connected to another Kapso project
* remove the number from previous providers or WhatsApp Business App registrations before retrying

In Kapso:

1. Go to **Connected numbers** → **Connect new number**
2. Select **Bring your own SIM**
3. Click through to open Meta embedded signup

Meta may show the partner name as **Kapso** or **Kapso Connect**. Both are Kapso.

In Meta embedded signup:

1. Log in with the Facebook account that has access to your business. On **Seamlessly connect your account to Kapso**, review what Kapso will be able to do and click **Continue**.

   ![Meta embedded signup asks you to continue connecting the account to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-continue.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=7906482bacefdb4d32257601f34fcb1c)

2. On **Add your WhatsApp phone number**, keep **Enter a new phone number** selected. Do not choose **Use a display name with a virtual number instead**. Select the country code, enter the phone number you want Kapso to use, and click **Next**.

   ![Meta asks for the SIM phone number with the country code.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-phone-details.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=616253b553bc1a66b15a2d7e8db4716b)

3. On **Verify your phone number**, enter the 6-digit code that Meta sends by text message and click **Next**. If the code does not arrive, wait for the timer and request a new code, or switch the verification method to **Phone call**.

   ![Meta asks for the 6-digit verification code sent by text message.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-verification-code.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=a4c4f5346df5b3fc8bb7579344f6a07d)

4. On **Select the business assets to share with Kapso**, choose the **Business portfolio** for the business that owns this phone number.

   ![Meta asks you to select the business portfolio and WhatsApp Business account.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-business-portfolio.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=440dba7b2531fc208c5b0c83b53ef254)

5. In **WhatsApp Business account**, choose an existing account or keep **Create a WhatsApp Business account**, then click **Next**.

   ![Meta shows the selected business portfolio and WhatsApp Business account.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-assets.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=12d51c6483f4ba0f270d203cb2c07f3d)

6. On **Review what you'll share with Kapso**, review the requested access and click **Confirm**. Meta shows **Connecting your account** for a few moments.

   ![Meta shows the permissions Kapso will receive for the selected business and WhatsApp account.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-review-permissions.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=cc06d8e79fd1aaa37cd71d88d6d9364a)

7. When Meta shows **Your account is connected to Kapso**, click **Finish**. This final step sends you back to Kapso so the connection can be completed.

   ![Meta confirms that the account is connected to Kapso.](https://mintcdn.com/kapso/A0e7Tvhd4Wxb4m3R/images/connect-whatsapp/byosim-meta-connected.png?fit=max\&auto=format\&n=A0e7Tvhd4Wxb4m3R\&q=85\&s=316ec65ab1cd6593f217b0717099dc17)

After Meta returns you to Kapso, Kapso registers the number, creates the production WhatsApp configuration, and shows the number as connected.

![Kapso shows the SIM phone number as connected after Meta returns to the app.](https://mintcdn.com/kapso/42TG2gfzA5DLrWPX/images/connect-whatsapp/byosim-kapso-connected.png?fit=max\&auto=format\&n=42TG2gfzA5DLrWPX\&q=85\&s=e1b49d2b85d6c17a422c2a85604a1833)

If Meta accepts the flow but the WABA is still under review, the phone number can remain pending. Kapso saves the WABA status and shows it in the UI as the number's **Business Account Status**, such as **Review pending**, **Review deferred**, **Review rejected**, or **Restricted**. When Meta sends the review update, Kapso automatically retries phone registration. While waiting, make sure the Meta Business Portfolio has complete business information and check [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) for the number status. If Meta points to account-level setup, use [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) to check WABA status, business verification, billing, and payment prompts.

If SMS or voice verification keeps failing, stop retrying before Meta rate-limits the number. Confirm the number is not still attached to another WABA, provider, WhatsApp Business App account, or Kapso project before trying again.

If Meta does not show the expected number, SMS or voice verification fails, or Meta says the number is already linked somewhere else, see [Bring your own SIM troubleshooting](https://docs.kapso.ai/docs/how-to/whatsapp/bring-your-own-sim-troubleshooting.md).

## Manual setup and Meta apps

If you manually add a WhatsApp phone number instead of using embedded signup, Kapso may need your Facebook App ID and App Secret to validate incoming Meta webhooks.

You can find these in Meta under **App settings** → **Basic**.

In Kapso:

1. Go to **Phone numbers**
2. Open **Meta apps**
3. Create a Meta app with your App ID and App Secret
4. Edit the manually added phone number
5. Select the Meta app
6. Save

If a manually added number can send messages but does not receive inbound messages, check this first. This is not your WhatsApp access token; App Secrets are stored write-only in Kapso.

## If the popup doesn't load

Disable ad blockers and privacy extensions. They block Meta's SDK. Try Chrome or Firefox if Safari isn't working.

### Why to avoid the display name option

In all of the signup flows, the **Phone number** dropdown in Meta includes **Use a display name with a virtual number instead** (older versions of the flow call it **Use a display name only**). If you choose it, you may complete Meta signup but end up with a limited Meta-managed number instead of the intended production number.

Consequences:

* The connected number may not be the pre-verified number, project-pool number, or SIM number you meant to connect.
* These limited Meta-managed numbers can stop working after about 5 messages and ask for display-name approval before you can keep using them.
* Display-name approval can take a long time, and Meta may defer the decision. While the decision is pending or deferred, you may be left unable to use the number.
* You may need to delete or disconnect that WhatsApp profile and restart onboarding through the correct Kapso flow.

> [!NOTE]
>
> Need help? In Kapso, go to the sidebar, click 'Help' and select 'Support'


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.