WhatsApp Embedded Signup: A Builder's Guide for SaaS

Your customers keep asking for WhatsApp inside your product. You do not want to email each of them a list of Meta steps, collect their tokens in a spreadsheet and register their numbers by hand. You want a "Connect WhatsApp" button that does the onboarding and hands your app the access it needs.

That button is WhatsApp Embedded Signup. It is Meta's onboarding popup for partners: your customer signs in with Facebook, picks or creates their business assets, verifies a phone number, and your app comes away with their IDs and a code you exchange for a customer-scoped token. This guide is for the people building that integration: which partner role you need, what has to be approved first, what customers see, the exact code on each side, and the limits that catch teams in their first month.

What Embedded Signup does

Embedded Signup runs on Facebook Login for Business and Meta's JavaScript SDK. When a customer finishes the flow, three things have happened: Meta collected their business details, created whatever WhatsApp assets were missing, and granted your app access to them.

The popup then returns three values to the page that opened it: the customer's waba_id, their phone_number_id, and an exchangeable code. Since Meta's 2026 account model change, waba_id denotes a Messaging account (templates, billing, webhook subscriptions), which the standard flow creates per partner. The value and format are unchanged, so existing code keeps working. The phone number itself now sits in a separate WhatsApp account that the customer owns.

Customers onboarded this way own their assets and keep full access to WhatsApp Manager. Meta is explicit that you cannot restrict that access.

Pick your partner role first

You can't launch Embedded Signup as an ordinary app. You must be a Tech Provider or a Solution Partner, and the choice decides who bills your customers.

Most SaaS products start as Tech Providers. You charge your subscription; Meta charges your customer for messages. If you later need to invoice usage yourself, you can build a Multi-Partner Solution with a Solution Partner who shares their credit line. Our guide to WhatsApp API for SaaS compares this with using a provider's API instead.

What must be approved before your first customer

Becoming a Tech Provider is done from the App Dashboard, under the WhatsApp use case's Tech Provider onboarding page.

1. Business verification for your own portfolio. See our guide to Meta business verification.
2. App Review for advanced access to whatsapp_business_messaging and whatsapp_business_management. Meta asks for two screen recordings: a message sent from your app arriving in a WhatsApp client, and your app creating a template. Recordings of the API Setup curl command and of WhatsApp Manager are accepted in their place. Your app also needs an icon, privacy policy and category.
3. Facebook Login for Business configuration. Create one from the template named "WhatsApp Embedded Signup Configuration With 60 Expiration Token" and save the configuration ID. Ask only for assets you need; Meta warns that requesting catalogs you don't use makes customers abandon the flow.
4. Allowed domains. In Client OAuth settings, turn on the login toggles and add every HTTPS domain that will host the button, including staging.
5. Webhooks. Subscribe your app to account_update, which fires when a customer completes the flow.

Until App Review passes, the permissions only appear in the flow for people with a role on your app, which is enough for testing.

What your customers see

From v4 on, Meta is moving the flow to a phone-number-first order (still rolling out), so problems with the number surface before anything is created:

1. Sign in with Facebook or Meta Business credentials.
2. Review what your app will be allowed to access.
3. Enter a business phone number, or pick an existing one.
4. Verify it with a code by SMS or phone call.
5. Select or create a business portfolio and WhatsApp account.
6. Review permissions, then a success screen.

If you enable WhatsApp Business app onboarding and the customer enters a number already on the Business app, the flow switches to coexistence automatically: they scan a QR code inside the app instead of deleting their account. Our WhatsApp coexistence guide covers that branch. The flow is localised into 30 languages based on the customer's Facebook language.

The code on both sides

The browser part loads the SDK, listens for the session message that carries the IDs, and launches the popup with your configuration ID:

<script async defer crossorigin="anonymous" src="https://connect.facebook.net/en_US/sdk.js"></script>
<script>
  window.fbAsyncInit = () => FB.init({ appId: "APP_ID", xfbml: true, version: "v23.0" });

  let session = null;
  window.addEventListener("message", (event) => {
    if (!event.origin.endsWith("facebook.com")) return;
    try {
      const data = JSON.parse(event.data);
      if (data.type === "WA_EMBEDDED_SIGNUP") session = data; // FINISH, CANCEL or ERROR
    } catch {}
  });

  function connectWhatsApp() {
    FB.login((response) => {
      const code = response.authResponse?.code;
      if (!code) return;
      // Send immediately: the code is only valid for about 30 seconds.
      fetch("/api/whatsapp/onboard", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ code, ...session?.data }),
      });
    }, {
      config_id: "CONFIGURATION_ID",
      response_type: "code",
      override_default_response_type: true,
      extras: { setup: {} },
    });
  }
</script>

On your server, finish onboarding with server-to-server calls. Never do these in the browser.

const GRAPH = "https://graph.facebook.com/v23.0";

export async function onboard({ code, waba_id, phone_number_id }) {
  // 1. Exchange the code for a business token scoped to this customer
  const q = new URLSearchParams({ client_id: APP_ID, client_secret: APP_SECRET, code });
  const { access_token } = await fetch(`${GRAPH}/oauth/access_token?${q}`).then((r) => r.json());
  const auth = { Authorization: `Bearer ${access_token}` };

  // 2. Subscribe your app to the customer's Messaging account webhooks
  await fetch(`${GRAPH}/${waba_id}/subscribed_apps`, { method: "POST", headers: auth });

  // 3. Register the number for Cloud API (skip this for coexistence onboarding)
  await fetch(`${GRAPH}/${phone_number_id}/register`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({ messaging_product: "whatsapp", pin: newSixDigitPin() }),
  });

  // 4. Store the token encrypted, keyed to this customer
  await saveTenant({ waba_id, phone_number_id, token: access_token });
}

After that, Tech Provider customers add a payment method in WhatsApp Manager before they can send; Solution Partners share their credit line instead. Use the current Graph API version from Meta's changelog everywhere you see v23.0. Business tokens are explained in our guide to the WhatsApp API access token.

Limits and gotchas

• Onboarding cap. By default you can onboard 10 new customers in a rolling 7 days. Business verification, App Review and Access Verification lift it to 200; beyond that Meta points you to its partner programme.
• Session events matter. CANCEL events include the screen where the customer quit, and ERROR events include a session ID for support. Log both; they are your funnel data.
• Versions. Meta deprecated v2 and v3 on October 15, 2026, and calls without a valid version are served as v4. The latest is v5, released October 20, 2026, where Business app onboarding is on by default. Set the version in the extras object as Meta's versions page describes.
• Sandbox accounts let you test without creating real portfolios. They last 30 days and their numbers can't send messages.
• No code needed option. Hosted Embedded Signup gives you a Meta-hosted page and link instead of SDK code, for Cloud API onboarding only, with no customisation.
• Developer-app accounts. WhatsApp accounts originally created through a developer app can't be onboarded through the flow.

Where Tenashi fits

If you are building a multi-tenant product on Meta's platform, Embedded Signup is the road, and Tenashi is not a substitute for becoming a Tech Provider. Where Tenashi helps builders is earlier and narrower. Verification and App Review take time, and you may want to prove the workflow first. Tenashi's API runs on a WhatsApp number your team already uses: link it by QR, then POST /api/v1/messages to a phone number or an existing group and receive signed webhooks for replies, on any paid plan from $18/mo. Your own sales and support team can also use the shared inbox to talk to the customers you are onboarding.

It is not Meta's platform: no templates, buttons or green tick, paced sends, and not built for OTPs or high volume. For the full map of options, see the complete guide to the WhatsApp API.

Read the API docs · Get started

FAQ

Do I need to be a BSP to use WhatsApp Embedded Signup?

No. You need to be either a Tech Provider or a Solution Partner, and most SaaS teams start as Tech Providers. That requires business verification and App Review for the two WhatsApp permissions, not a Meta Business Partner contract. The main difference is billing: Tech Provider customers pay Meta directly with their own payment method.

How long is the Embedded Signup code valid?

Meta says the exchangeable token code has a time-to-live of 30 seconds. Send it to your server the moment the login callback fires and exchange it there for the customer's business token. If you test by copying the code into curl by hand, prepare the exchange command before you start the flow.

Who pays for messages sent by customers onboarded through Embedded Signup?

It depends on your role. If you are a Tech Provider, each customer adds a payment method to their own Messaging account and Meta bills them for messages, while you bill your subscription. If you are a Solution Partner, you share your credit line during onboarding and invoice customers for usage yourself.

Can customers connect a number already on the WhatsApp Business app?

Yes, if you enable WhatsApp Business app onboarding, often called coexistence. In v4 you set a feature type in the launch options; in v5 it is on by default. The customer keeps using the app on their phone, history can be synced, and you skip the registration call because the number is already registered.

How many customers can I onboard per week?

By default, 10 new business customers in a rolling seven-day window. Once you complete business verification, App Review and Access Verification, Meta raises it to 200 automatically. If you need more than 200 a week, Meta directs you to apply as a Meta Business Partner. Only newly onboarded customers count.

---

Get your role, App Review and configuration in place first; the code itself is the short part. If you want to test a WhatsApp workflow on a real number while that happens, read the Tenashi API docs.