Implementation
Updated: Nov 4, 2025 This document explains how to implement Embedded Signup v4 and capture the data it generates to onboard business customers onto the WhatsApp Business Platform.Before you start
You must already be a Solution Partner or Tech Provider. If your business customers will be using your app to send and receive messages, you should already know how to use the API to send and receive messages using your own WhatsApp Business Account and business phone numbers. You should also know how to create and manage templates and have a webhooks callback endpoint properly set up to digest webhooks. You must be subscribed to the account_update webhook, as this webhook is triggered whenever a customer successfully completes the Embedded Signup flow, and contains their business information that you will need. If you are a Solution Partner, you must already have a line of credit. The server where you will be hosting Embedded Signup must have a valid SSL certificate.Step 1: Add allowed domains
Load your app in the App Dashboard and navigate to Facebook Login for Business > Settings > Client OAuth settings:
Set the following toggles to Yes:
Client OAuth login
Web OAuth login
Enforce HTTPS
Embedded Browser OAuth Login
use Strict Mode for redirect URIs
Login with the JavaScript SDK
Embedded Signup relies on the JavaScript SDK. When a business customer completes the Embedded Signup flow, the customer’s WABA ID, business phone number ID, and an exchangeable token code will be returned to the window that spawned the flow, but only if the domain of the page that spawned the flow is listed in the Allowed domains and Valid OAuth redirect URIs fields.
Add any domains where you plan to host Embedded Signup, including any development domains where you will be testing the flow, to these fields. Only domains that have enabled HTTPS are supported.
Step 2: Create a Facebook Login for Business configuration
A Facebook Login for Business configuration defines which permissions to request, and what additional information to collect, from business customers who access Embedded Signup. Navigate to Facebook Login for Business > Configurations:
Click the Create from template button and create a configuration from the WhatsApp Embedded Signup Configuration With 60 Expiration Token template. This will generate a configuration for the most commonly used permissions and access levels.
Alternatively, you create a custom configuration. To do this, in the Configurations panel, click the Create configuration button and provide a name that will help you differentiate the custom configuration from any others you may create in the future. When completing the flow, be sure to select the WhatsApp Embedded Signup login variation:
Select your products you want to onboard for this configuration.
When choosing assets and permissions, select only those assets and permissions that you will actually need from your business customers. Assets that are already selected are added by default.
For example, if you select the Catalogs asset but don’t actually need access to customer catalogs, your customers will likely abandon the flow at the catalog selection screen and ask you for clarification.
When you complete the configuration flow, capture your configuration ID, as you will need it in the next step.
Step 3: Add Embedded Signup to your website
Add the following HTML and JavaScript code to your website. This is the complete code needed to implement Embedded Signup. Each portion of the code will be explained in detail below.SDK loading
This portion of the code loads the Facebook JavaScript SDK asynchronously:SDK initialization
This portion of the code initializes the SDK. Add your app ID and the latest Graph API version here.| Placeholder | Description | Example value |
|---|---|---|
<APP_ID> | Required. Your app ID. This is displayed at the top of the App Dashboard. | 21202248997039 |
<GRAPH_API_VERSION> | Required. Graph API version. This indicates which version of Graph API to call, if you are relying on the SDK’s methods to perform API calls. In the context of Embedded Signup, you won’t be relying on the SDK’s methods to perform API calls, so we recommend that you just set this to the latest API version: v24.0 | v24.0 |
Session logging message event listener
This portion of the code creates a message event listener that captures the following critical information: The business customer’s newly generated asset IDs, if they successfully completed the flow The name of the screen they abandoned, if they abandoned the flow An error ID, if they encountered an error and used the flow to report it| Placeholder | Description | Example value |
|---|---|---|
<CUSTOMER_BUSINESS_PHONE_NUMBER_ID> | The business customer’s business phone number ID | 106540352242922 |
<CUSTOMER_WABA_ID> | The business customer’s WhatsApp Business Account ID. | 524126980791429 |
<CUSTOMER_BUSINESS_PORTFOLIO_ID> | The business customer’s business portfolio ID. | 2729063490586005 |
<CUSTOMER_AD_ACCOUNT_ID> | The business customer’s ad account ID | 4052175343162067 |
<CUSTOMER_PAGE_ID> | The business customer’s Facebook Page ID | 1791141545170328 |
<CUSTOMER_DATASET_ID> | The business customer’s dataset ID | 524126980791429 |
<FLOW_FINISH_TYPE> | Indicates the customer successfully completed the flow. Possible Values: FINISH: Indicates successful completion of Cloud API flow.FINISH_ONLY_WABA: Indicates user completed flow without a phone number.FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING: Indicates user completed flow with a whatsapp business app number. | FINISH |
| Placeholder | Description | Example value |
|---|---|---|
<CURRENT_STEP> | Indicates which screen the business customer was viewing when they abandoned the flow. See Embedded Signup flow errors for a description of each step. | PHONE_NUMBER_SETUP |
| Placeholder | Description | Example value |
|---|---|---|
<ERROR_MESSAGE> | The error description text displayed to the business customer in the Embedded Signup flow. See Embedded Signup flow errors for a list of common errors. | Your verified name violates WhatsApp guidelines. Please edit your verified name and try again. |
<ERROR_ID> | Error ID. Include this number if you contact support. | 524126 |
<SESSION_ID> | Unique session ID generated by Embedded Signup. Include this ID if you contact support. | f34b51dab5e0498 |
<TIMESTAMP> | Unix timestamp indicating when the business customer used Embedded Signup to report the error. Include this value if you are contacting support. | 1746041036 |
<CURRENT_STEP> values and the screens they correspond to.
Note that the try-catch statement in the code above has two statements that can be used for testing purposes:
Response callback
Whenever a business customer successfully completes the Embedded Signup flow, we will send an exchangeable token code in a JavaScript response to the window that spawned the flow.code constant.
Add your own, custom code to the if-else statement that sends this code to your server so you can later exchange it for the customer’s business token when you onboard the business customer.
The exchangeable token code has a time-to-live of 30 seconds, so make sure you are able to exchange it for the customer’s business token before the code expires. If you are testing and just dumping the response to your JavaScript console, then manually exchanging the code using another app like Postman or your terminal with cURL, we recommend that you set up your token exchange query before you begin testing.
Note that the if-else statement in the code above has two statements that can be used for testing purposes:
Launch method and callback registration
This portion of the code defines a method which can be called by anonclick event that registers the response callback from the previous step and launches the Embedded Signup flow.
Add your configuration ID here.

