whatsapp.embeddedSignup

Meta's Embedded Signup (Facebook Login for Business) lets your users connect their own WhatsApp Business Account to your platform with an in-app popup — without manually navigating Meta Business Manager or creating developer apps.

The whatsapp.embeddedSignup module provides helpers for generating the client popup script, exchanging the short-lived authorization code for a long-lived Business Integration token on your backend, and subscribing your app to the new WABA's webhooks.

The onboarding flow

1. Frontend: Render the Facebook JavaScript SDK popup with your Login for Business configuration ID.
2. Browser response: When the user finishes the popup, Meta returns a short-lived code (and sends a window.postMessage containing phone_number_id and waba_id).
3. Backend exchange: Send the code to your server and call whatsapp.embeddedSignup.exchangeCodeForToken(code) to obtain a System User access token.
4. Webhook subscription: Call whatsapp.embeddedSignup.subscribeToWaba(wabaId, { accessTokenOverride }) so your application receives incoming messages and delivery receipts for that customer.

1. Generate the Frontend Script

Generates the standard HTML <script> and <button> markup for initiating FB.login() with your configuration ID:

const scriptHtml = whatsapp.embeddedSignup.getLoginScript({
  appId: process.env.WA_APP_ID!,
  configId: process.env.WA_EMBEDDED_CONFIG_ID!,
  triggerElementId: "connect-whatsapp-btn",
  graphApiVersion: "v21.0",
});

2. Exchange Authorization Code for Access Token

Exchanges the short-lived OAuth authorization code sent from the browser callback for a Business Integration access token. Requires appId and appSecret in the client configuration.

import { whatsapp } from "@/lib/whatsapp";

export async function POST(req: Request) {
  const { code } = await req.json();

  // Exchange the short-lived code for a system user access token
  const { data: tokenData, error: tokenError } =
    await whatsapp.embeddedSignup.exchangeCodeForToken(code);

  if (tokenError) {
    return Response.json({ error: tokenError.message }, { status: 400 });
  }

  const { accessToken } = tokenData;

  // Store accessToken, wabaId, and phoneNumberId in your database for this tenant
  return Response.json({ success: true, accessToken });
}

3. Subscribe to the Customer's WABA Webhooks

Subscribes your Meta App to receive webhook events for the customer's newly linked WhatsApp Business Account. Pass the customer's fresh token via accessTokenOverride:

const { data, error } = await whatsapp.embeddedSignup.subscribeToWaba(
  customerWabaId,
  { accessTokenOverride: customerAccessToken }
);

if (error) {
  console.error("Failed to subscribe WABA to webhooks:", error.message);
} else {
  console.log("Successfully subscribed to customer WABA webhooks!");
}

Parameters and Options