> Source: https://docs.virtuo.in/vibot/getting-started/connect-whatsapp
> Connect your WhatsApp Business number to Vibot via Meta's official Embedded Signup flow — the definitive step-by-step guide.

# 2. Connect WhatsApp

Vibot is a Meta-registered Business Solution Provider (BSP). Connecting your number takes 3–5 minutes and is done entirely through Meta's official **Embedded Signup** popup — no SIM swap, no porting, no copying tokens by hand.

<Video src="/videos/getting-started/connect-whatsapp.mp4" caption="The seven steps of the Embedded Signup popup, in 20 seconds." />

## Before you start

<Callout type="warning">
You will need **all four** of the following. Stop and gather them before starting — the popup will fail silently if any are missing.

- A **Facebook Business account** linked to your Facebook login. Personal accounts cannot complete Embedded Signup.
- **Admin access to a Meta Business Manager**. If you only have Employee access, ask your Business Manager admin to grant you Admin on the Business Portfolio first.
- A **WhatsApp-eligible phone number** that can receive SMS or voice OTP from Meta during signup. Toll-free numbers, VoIP numbers, and shared numbers will not work.
- **Popups allowed** on `vibot.virtuo.in`. Most browsers silently kill third-party popups by default and the Embedded Signup window will never open.
</Callout>

<Steps>

### Open the Connect WhatsApp page

From the dashboard, click **Connect WhatsApp** on the Overview tile, or open **Connect WhatsApp** from the left sidebar.

You will see one of three states at the top of the page:

- **Not Connected** (grey) — no number is attached yet.
- **Pending Registration** (amber, pulsing dot) — a number is attached but Meta still needs two-step verification.
- **Connected** (green) — your number is live and receiving messages.

### Walk the Embedded Signup popup

Click **Connect WhatsApp Business**. A Facebook-hosted popup opens. The popup is sandboxed by Facebook — you must complete the entire flow inside this window. Do not close it midway.

<Steps>

#### Log in to Facebook

If you are not already logged in, the popup asks for your Facebook Business credentials. Use the account that has admin rights on your Business Portfolio — not a personal account.

#### Select or create a Meta Business Portfolio

Pick the Business Portfolio that should own this WABA. If you do not have one, the popup lets you create one inline.

#### Pick "Create new WhatsApp Business Account"

Two options appear:

- **Create new WhatsApp Business Account** — pick this if you don't already have a WhatsApp Business Account, or if you want a fresh one for this number. Recommended for most customers.
- **Use existing WhatsApp Business Account** — pick this only if you have an established WABA you want to bring into Vibot and your Facebook user is an admin of its Business Portfolio.

<Callout type="warning">
The choice you make here cannot be changed for this number later — you would have to repeat Embedded Signup with a different phone number to switch.
</Callout>

#### Enter business details

Provide your business display name, category, and a short description. The **display name** is what your customers see in their WhatsApp chat header — Meta is strict about it. It must match your registered business and cannot contain promotional phrases like "Best deals" or "24/7 sale."

#### Enter the phone number

Type the number you want to connect, in international format (e.g. `+91 98765 43210`).

<Callout type="warning">
The number must **not** be currently registered in the WhatsApp consumer app or WhatsApp Business app on a phone. Meta blocks signup with a "Number is registered elsewhere" error if it is. If you are reusing a personal-WhatsApp number, open WhatsApp on your phone first and go to **Settings → Account → Delete my account** to release it. Wait 5 minutes, then try Embedded Signup again.
</Callout>

#### Verify the number via OTP

Meta sends a 6-digit one-time password to your number by SMS or voice call. Choose whichever method works for your number and enter the code in the popup.

#### Accept Meta's terms

Tick the boxes for the **WhatsApp Business Messaging Policy** and **Meta Commerce Policy**. These are Meta's terms, not Vibot's — we cannot waive or modify them.

#### Click Continue, then Finish

The popup closes itself when complete. The Vibot dashboard automatically updates with a green **Connected** badge showing your Phone Number ID and WABA ID.

</Steps>

### Fix Registration (if status is amber)

After Embedded Signup completes, the status often shows **Pending Registration** (amber, pulsing dot). This is normal. Meta has attached your number to Vibot but still requires you to confirm two-step verification before sending is enabled.

1. Click **Fix Registration**.
2. A dialog asks for your **6-digit two-step verification PIN**.
3. Find this PIN in the WhatsApp Business app on the phone that originally owned this number: **Settings → Account → Two-step verification**. If you never set one, set it now and use that value.
4. Enter the 6-digit PIN and click **Confirm & Connect**.
5. The status flips to green **Connected** within a few seconds.

<Callout type="error">
**This PIN is the WABA two-step verification PIN.** It is **not** your Facebook password. It is **not** your WhatsApp account password. It is **not** the OTP you received during the popup OTP step. It is the 6-digit PIN configured in the WhatsApp Business app's **Two-step verification** screen. Entering the wrong value here is the single most common onboarding failure.
</Callout>

</Steps>

## Common pitfalls

Real failure modes we see in support tickets, with the exact fix.

- **"The popup never opens when I click Connect."** Your browser is blocking popups. Allow popups on `vibot.virtuo.in` (in Chrome: address-bar popup icon → Always allow). Reload the dashboard, then retry.
- **"Number is already registered elsewhere."** The number is active in the WhatsApp consumer or WhatsApp Business app, or on another BSP. Delete it from the WhatsApp mobile app (**Settings → Account → Delete my account**), wait 5 minutes, and retry. If the number was on another BSP, ask that BSP to release it first.
- **"The permissions screen is blank or stuck loading."** Facebook is not logged in. Open a new tab, go to facebook.com and log in to your Business account, then come back to the Vibot tab and retry. The popup needs an active Facebook session in the same browser.
- **"Status is stuck on Pending Registration even after clicking Fix Registration."** Wait 60 seconds and refresh the page. If still amber, you almost certainly entered the wrong PIN — re-check the WhatsApp Business app at **Settings → Account → Two-step verification** and confirm the value. The PIN is set per-WABA, not per-Facebook-account.
- **"Status was green yesterday, but messages started failing today with no clear error."** Your `code_verification_status` has likely expired. Meta periodically requires SMS or voice OTP re-verification of registered numbers and currently there is no self-serve UI in the dashboard for this. Email `pratham@tellusys.in` with your Phone Number ID and we will re-verify from our side.
- **"I picked the wrong WABA in the popup."** Go back to **Connect WhatsApp** and run Embedded Signup again, picking the correct WABA this time. The new connection replaces the previous one — your message history and agent config are preserved.
- **"The Embedded Signup popup is in a different language."** That is the language your Facebook account is set to, not the language Vibot is requesting. Switch your Facebook language at facebook.com/settings/?tab=language, then retry. Vibot has no control over the popup contents.

## What happens behind the scenes

When you finish Embedded Signup, Meta returns a long-lived WhatsApp access token to Vibot. We immediately encrypt this token with **AES-256-GCM** before writing it to our database — the plaintext token is never persisted on disk. We then subscribe Vibot's webhook to your WABA via the official Meta Cloud API.

We use **Meta's official Cloud API only**. Vibot does not use Baileys, WPPConnect, or any unofficial WhatsApp library. Every message in and out of your number flows through Meta's audited infrastructure. Your conversation data is fully tenant-isolated — no other Vibot customer can read your messages, your contacts, or your agent configuration.

## Reconnecting a different number

Go to **Connect WhatsApp** and complete Embedded Signup again with the new number. The new connection replaces the existing one for this tenant. Conversation history from the previous number remains accessible in **Chats** but new inbound messages will only arrive on the newly connected number.

## Next step

Configure the AI agent that will reply on this number → [**Configure the agent**](/vibot/getting-started/configure-agent).

If you plan to send outbound campaigns, also read:

- [**Meta Business setup**](/vibot/meta-setup) — Business Verification, display name, WhatsApp Manager. Decides whether your number can scale past 250 sends/day.
- [**Warm up a new number**](/vibot/sending/warm-up-new-number) — week-by-week ramp so your first blast doesn't crater your quality rating.