Common Embedded Signup (onboarding) errors

You connect your WhatsApp account to BSG through Meta's Embedded Signup flow. Any problems here happen while connecting — before you send anything. As with sending, BSG surfaces Meta's own errors, and the complete list lives in Meta's Embedded Signup flow errors documentation.

This guide covers the ones you're most likely to hit. (For errors while sending, see Common WhatsApp API errors.)

How Embedded Signup reports problems

Embedded Signup runs in a popup and posts a message event back to the page that opened it:

• ERROR — something failed during the flow.
• CANCEL — the user closed the flow before finishing. The payload's data.current_step tells you which screen they were on, so you can guide them back:

{ "data": { "current_step": "PHONE_NUMBER_VERIFICATION" },
  "type": "WA_EMBEDDED_SIGNUP", "event": "CANCEL", "version": 3 }

Steps include BUSINESS_ACCOUNT_SELECTION, WABA_PHONE_PROFILE_PICKER, WHATSAPP_BUSINESS_PROFILE_SETUP, PHONE_NUMBER_SETUP, PHONE_NUMBER_VERIFICATION, and PERMISSIONS.

Most common onboarding issues

1. You don't have permission to create/select the WhatsApp Business Account

Meta: "User does not have permission to create WhatsApp Business Accounts."

Why you might see it: you're not an Admin of the Meta Business Portfolio you selected.

What to do: get Admin access to that Business Portfolio (or choose one you administer), then retry.

2. You can't select your existing WhatsApp Business Account

Why you might see it: Meta doesn't allow selecting a WABA in Embedded Signup if it was created through a different app or provider.

What to do: share it with BSG from Meta Business Suite → Business Settings → WhatsApp Accounts (using BSG's Business Portfolio ID) instead of picking it in the signup window.

3. Your WABA is already connected to two partners

Why you might see it: a WABA can be shared with a maximum of two partners at once, so BSG can't be added as a third.

What to do: in Meta Business Settings → WhatsApp Accounts → [your WABA] → Partners, remove one existing partner to free a slot, then re-run the connection. (See Connecting to BSG as a parallel second provider for the full flow.)

4. Your Facebook/Business account is too new or has been flagged

Meta: e.g. "Your Facebook account is too new to create a business account. Try again in an hour," or messages about limits on how many businesses you can create.

Why you might see it: brand-new or previously-flagged Facebook accounts are limited from creating Business/WhatsApp accounts.

What to do: use an established, active Facebook account with Admin rights, or wait and retry.

5. The flow was closed before finishing (CANCEL)

Why you might see it: the user exited at one of the screens (permissions, phone verification, etc.).

What to do: read data.current_step from the CANCEL event to see where they stopped, and prompt them to resume — most often at PHONE_NUMBER_VERIFICATION (they didn't enter the code) or PERMISSIONS (they didn't grant access).

Onboarding problems can surface later as send errors

Some setup issues don't block the flow but cause failures once you start sending — for example, no payment method on Meta (send error 131042) or an incomplete phone-number registration. If your connection finished but sends fail, cross-check with Common WhatsApp API errors.

Where to find every other error

Because BSG mirrors Meta, any onboarding error not listed here is defined in Meta's Embedded Signup flow errors documentation.

Related guides

• Getting started with 1-way WhatsApp on BSG — the full connection walkthrough.
• Connecting to BSG as a parallel second provider — connecting alongside an existing provider.
• Common WhatsApp API errors — problems while sending.