# Meta Embedded Signup Integration

> Connect a WhatsApp number to Avox through Meta's own sign-up window - requirements, setup, checks, common errors and FAQ.

Source: https://docs.theavoxai.com/integrations/embedded-signup

**Embedded Signup** is Meta's own sign-up window for WhatsApp business platforms. Avox opens it so
you can connect a number in one sitting: sign in with Facebook, choose your business and number,
approve Avox's access, and finish. No tokens to copy, no developer setup.

This page is the quick guide. Every screen of Meta's window is described on
[Embedded Signup](https://docs.theavoxai.com/whatsapp/embedded-signup).

## Requirements

| You need | Why |
| --- | --- |
| An active Avox plan with a free number slot | Avox checks this on Connections and again before saving the connection. See [Plans](https://docs.theavoxai.com/plans). |
| A Facebook account that's an admin of your Business Portfolio and WhatsApp Business Account | Meta only lets admins share an account with a platform. |
| Pop-ups allowed for the Avox dashboard, opened at its `https://` address | Meta's window opens as a pop-up, and only on a secure page. |
| A public `https://` URL for your own server | The wizard's **Webhook setup** step asks for it. It's where [Message forwarding](https://docs.theavoxai.com/integrations/webhooks) sends new customer messages once you turn it on. |
| Your phone with the WhatsApp Business app (Coexistence only) | You confirm the connection on the phone partway through. |
| A number that can receive an SMS or voice code (New number only) | Meta verifies the number that way. |

## Setup

**1. Start a connection**

On [Connections](https://docs.theavoxai.com/connections), click **Connect another number**. With no number connected yet, the wizard opens on its own.

**2. Choose the number type**

**Existing number (Coexistence)** or **New number (Bot only)**. This picks Meta's path. Click **Next**.

**3. Fill in Webhook setup**

Enter a **Connection Name** and your server's **Webhook URL** (`https://`). A **Verify Token** is optional but recommended - click **Generate** for a random one. Click **Next**. See [Message forwarding](https://docs.theavoxai.com/integrations/webhooks).

**4. Test endpoint**

Click **Test endpoint**. Avox checks something answers at your URL, shows the result, then moves on to the last step either way.

**5. Click Continue to Meta Embedded Signup**

Copy your **Webhook URL** and **Verify Token** if your server needs them, then click the button. Meta's window opens, and the **What to expect during setup** panel shows each screen and a live status.

**6. Follow Meta's screens**

Pick your number, confirm the profile (Coexistence), select the business portfolio, scan the QR code with your phone (Coexistence), confirm the WhatsApp Business Account, and review what you share with Avox.

**7. Click Finish**

Keep the window open until it closes on its own. Avox takes you back to **Connections**.

## Check it's working

- The status chip in the wizard turns **Connected**, and you land on [Connections](https://docs.theavoxai.com/connections)
  with the new number listed as **Connected**.
- The connection's page shows **WABA ID**, **Phone Number ID** and **Business ID**.
- The Switchboard's Admins get a "number connected" email.

## Common errors

The wizard shows **The connection didn't go through** with the reason,
[AVX-3002](https://docs.theavoxai.com/error-codes/avx-3002), and "Meta error" with Meta's number when there is one.

| Reason shown | Fix |
| --- | --- |
| "You closed the Meta signup window before the connection finished." | Click **Retry connection** and leave the window open until it closes itself. On Coexistence, also tap **Connect** on your phone. |
| Meta's own message | Follow it. If it mentions a phone number or code, use a number that can receive one. Look up the Meta error number in Meta's Embedded Signup error reference. |
| "Meta's popup never responded..." | Close any leftover pop-up or tab from the attempt, then retry. |
| "Meta blocks its signup popup from opening on a plain http:// page." | Open the dashboard at its normal `https://` address. |
| "Meta confirmed the signup, but Avox couldn't finish setting up the connection on our end." | Check your plan has a free number slot and that the number you picked sits inside the WhatsApp Business Account you approved. Then retry. If it repeats, contact [Support](https://docs.theavoxai.com/support) with the code shown. |
| [AVX-3009](https://docs.theavoxai.com/error-codes/avx-3009) on Connections, with **Connect another number** unavailable | Every number slot on your plan is in use. Pause or delete a number, or move to a bigger plan on [Billing](https://docs.theavoxai.com/billing). See [Plans](https://docs.theavoxai.com/plans). |
| The connection shows **Error** on Connections | Setup didn't finish on Meta's side. Connect the number again. |

## Limits

- Numbers you can connect: set by your plan. See [Plans](https://docs.theavoxai.com/plans). A paused number frees its slot.
- Meta gives a brand-new Business Portfolio fewer options at first - use an existing one when you
  have it.
- The chat history choice on your phone (Coexistence) is one-time, so choose the one you want to
  keep.

## Security

- You sign in on Meta's own site. Avox never sees your Facebook password.
- In **Review what you share with Avox**, Meta lists exactly which portfolio and WhatsApp Business
  Account Avox gets access to. Nothing else is shared.
- You can remove Avox's access at any time from your Business Portfolio settings on Meta.
- Continuing to Embedded Signup records your agreement to Avox's Terms of Service and your
  acknowledgement of the Privacy Policy.

## Build your own server for Meta Embedded Signup

Your own server isn't involved. Embedded Signup happens entirely between your browser, Meta's window and Avox - Avox stores the connection and subscribes it to Meta's events for you. Once the number is connected, your server can send through it with the [Avox API](https://docs.theavoxai.com/integrations/avox-api).

## FAQ

**Do I need a Meta developer account?**

No. Avox's own Meta app is used; you only sign in with a Facebook account that manages your
business.

**Do I need a Meta payment method to finish?**

No. You can add one later in WhatsApp Manager. Meta bills message charges to the WhatsApp Business
Account.

**Who in my team can run signup?**

Any Admin or Manager in the Switchboard can run the wizard. After that, renaming the connection,
changing message forwarding, managing API keys, calling, pausing or deleting it is for Admins.

**The window closed and nothing happened. Was anything changed?**

No connection is created unless signup finishes. Your **Webhook setup** details stay saved, so
Connections shows a **Setup in progress** card - click **Resume setup** when you're ready.

**What exactly is shared with Avox?**

The Business Portfolio and WhatsApp Business Account listed on Meta's **Review what you share with
Avox** screen. Avox checks that the number you picked belongs to that account before saving the
connection.

**The number later needs reconnecting. Do I run signup again?**

Yes. If Meta's access for the number ends, API sends fail with
[`connection_not_ready`](https://docs.theavoxai.com/api/errors#connection_not_ready). Reconnect the number from
[Connections](https://docs.theavoxai.com/connections), going through Meta's window again.

**What if a connection stays on Connecting?**

Setup didn't finish on Meta's side. Run signup again for that number. If it stays in
**Connecting** for a day, you get a reminder email when **Setup reminders** is on in
[Compliance](https://docs.theavoxai.com/compliance).