Embedded Signup
- Embedded Signup | Developer Documentation
- Implementation | Developer Documentation
- Onboarding business customers as a Tech Provider or Tech Partner | Developer Documentation
- Onboarding business customers as a Solution Partner | Developer Documentation
- Cloud API flow | Developer Documentation
- Customizing the default flow | Developer Documentation
- Onboarding WhatsApp Business app users (aka "Coexistence") | Developer Documentation
- Pre-filling screens | Developer Documentation
- Pre-verified phone numbers | Developer Documentation
- Bypassing the phone number addition screen | Developer Documentation
- Website field optional | Developer Documentation
- Hosted Embedded Signup | Developer Documentation
- Automatic Events API | Developer Documentation
- Versions | Developer Documentation
- Version 4 | Developer Documentation
- Version 3 | Developer Documentation
- Version 3 Public Preview | Developer Documentation
- Version 2 Public Preview | Developer Documentation
- App-Only Install | Developer Documentation
Embedded Signup | Developer Documentation
Embedded Signup
Updated: Nov 25, 2025
Embedded Signup is an authentication and authorization desktop- and mobile-compatible interface that makes it easy for your business customers to generate the assets you will need to successfully onboard them to the WhatsApp Business Platform.
The Embedded Signup flow gathers business-related information from your business customers, automatically generates all WhatsApp assets needed by the platform, and grants your app access to these assets, so you can quickly provide your business customers with WhatsApp messaging services.
How it works
Embedded Signup leverages the Facebook Login for Business product and our JavaScript SDK. Once configured, you can add a link or button to your website or portal that launches the flow.
Business customers who click the link or button will be presented with a new window where they can:

Upon successful completion, Embedded Signup returns the customer’s WABA ID, business phone number ID, and an exchangeable token code, to the window that spawned the flow. You must send this data to your server and use it in a server-to-server call to:
When these steps are complete, if you are a Solution Partner or are partnered with one, the customer can begin using your or your partner’s app for messaging immediately. If you are not a Solution Partner, or not partnered with one, the customer must first attach a payment method to their WABA before they can begin messaging.
We’re testing a new experience in the Embedded Signup flow for all versions. The flow itself is unchanged, but after completion, you may see a new View your setup guide button. Clicking it will take you to a new setup guidance page in WhatsApp Manager, which offers next steps on:
Asset ownership
Business customers onboarded via Embedded Signup own all of their WhatsApp assets, which they can leverage with other Meta solutions such as Ads that Click to WhatsApp.
Business customers also have full access to WhatsApp Manager, which they can use to access their assets. Note that you cannot restrict this access in any way. Refer to available assets here.
Limitations
Onboarding limits
By default, you can onboard up to 10 new business customers in a rolling 7-day window. Only newly onboarded customers count against this limit. You can see your current onboarded customer count in the WhatsApp Manager > Partner overview panel. You will be notified by email if you approach this limit.
If you complete Business Verification, App Review, and Access Verification, we will automatically increase your limit to 200 new business customers in a rolling 7-day window. If you need to onboard more than 200 customers per week, apply to become a Meta Business Partner.
Note: Existing WhatsApp Business Accounts (WABAs) that were originally created via the developer app cannot be selected or onboarded directly through the Embedded Signup flow.
Business customer messaging limits
Business customers onboarded via Embedded Signup start with standard messaging limits, which can be increased through API usage.
Business customer phone number limits
Cloud API flow
See Cloud API Flow for descriptions of each screen that your business customers will be presented with as part of the default implementation of Embedded Signup.
Note that if you know information about your customer’s business, you can inject this data, which can significantly reduce the number of screens that your customers have to interact with.
Access tokens
Embedded Signup generates business tokens. When a business customer completes the Embedded Signup flow, an exchangeable token code will be returned as a message event and captured by the JavaScript SDK. You must exchange this code for a business token using a server-to-server call.
If you are a Tech Provider, you will use business tokens exclusively.
If you are a Solution Partner, you will use your system user access token (“system token”) to share your credit line with onboarded business customers, and business tokens for everything else. Note that the system user who the token represents must have granted your app the business_management permission, and must have been granted an Admin or Financial Editor role on your business portfolio, in order to be able to share your credit line.
Permissions
Embedded Signup can be configured to support business messaging products for your customers. If you are only interested in the Cloud API flow you are likely only going to need:

You can specify which permissions your app needs during the implementation process.
Note that while your app is in development mode, these permissions will appear in Embedded Signup’s authorization screen to anyone who has an admin, developer, or tester role on your app. However, once you switch your app to live mode, only permissions that have been approved for advanced access through the App Review process will appear in the flow.
Billing
Solution Partners
If you are a Solution Partner, you must already have a line of credit and have accepted the Credit Allocation API terms in the Business Settings > Payments panel in the Meta Business Suite. In addition, you must share your line of credit with any customers as part of the onboarding process.
Tech Providers and Tech Partners
If you are a Tech Provider or Tech Partner, your onboarded business customers must add a payment method to their WhatsApp Business Account. They can do this by following the steps described in our Add a credit card to your WhatsApp Business Platform account Help Center article.
Sandbox accounts
You can test the Embedded Signup flow using your own Facebook account, but this can result in additional business portfolios, WABAs, and business phone numbers. If you don’t want to clutter your Facebook account with test data, you can claim a sandbox test account instead, and use it to simulate a business customer completing the flow.
When you complete the flow using the sandbox account, the sandbox account’s WABA ID, business phone number ID, and an exchangeable token code will be returned, just as if it were a real customer completing the flow.
Sandbox account limitations
Claiming sandbox accounts
To claim your sandbox account:

Deleting sandbox accounts
Sandbox account deletion is being released gradually over several weeks, starting June 25, 2025.
If you are done testing and want to keep your testing environment clean, you can delete your sandbox account. Deleting a sandbox account is irreversible and removes all associated test data. If you accidentally delete your sandbox account but need to test again, you must claim a new one.
To delete your sandbox account:

555 business phone numbers
Business customers can claim up to two 555 business phone numbers. These numbers behave the same way as standard business phone numbers (subject to pricing rules, impacted by quality ratings, etc.), but must have their display names approved before they can be used to send messages. In addition, 555 numbers:
If your business customers are eligible for 555 numbers, the phone number addition screen will automatically give them the option to choose a 555 number:

WhatsApp Asset migration
Embedded Signup can be used to migrate onboarded business customer assets in several ways. See Migrating business customer assets.
App Review
You will not be able to onboard business customers until your app has been approved for advanced access for each of the permissions it requires.
See App Review to learn more about App Review and what you must provide in order to complete the process successfully.
Embedded Signup Integration Helper
The Embedded Signup Integration Helper is a setup and testing tool within the App Dashboard. The tool allows you to:
You can access the integration helper by navigating to App Dashboard > WhatsApp > Embedded Signup Builder.
Note: The Embedded Signup Integration Helper is available only for Business-type apps. You can view your app type at the top of the app dashboard.
Localization
The Embedded Signup flow is available in 30 languages. The localized flow is automatically triggered based on the language that the business customer uses Facebook in.
Arabic, Czech, Danish, Greek, English (UK), Spanish (Spain), Spanish, Finnish, French (France), Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian (bokmal), Dutch, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Swedish, Thai, Turkish, Vietnamese, Simplified Chinese (China), Traditional Chinese (Hong Kong), Traditional Chinese (Taiwan).
Next steps
Learn how to implement Embedded Signup into your website or portal.
Implementation | Developer Documentation
Implementation
Updated: Mar 25, 2026
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
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 loginWeb OAuth loginEnforce HTTPSEmbedded Browser OAuth Loginuse Strict Mode for redirect URIsLogin 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.
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 flowThe name of the screen they abandoned, if they abandoned the flowAn error ID, if they encountered an error and used the flow to report it
// Session logging message event listener
window.addEventListener('message', (event) => {
if (!event.origin.endsWith('facebook.com')) return;
try {
const data = JSON.parse(event.data);
if (data.type === 'WA_EMBEDDED_SIGNUP') {
console.log('message event: ', data); // remove after testing
// your code goes here
}
} catch {
console.log('message event: ', event.data); // remove after testing
// your code goes here
}
});
This information will be sent in a message event object to the window that spawned the flow and will be assigned to the data constant. Add your own custom code to the try-catch statement that can send this object to your server. The object structure will vary based on flow completion, abandonment, or error reporting, as described below.
Successful flow completion structure:
On the final screen, both clicking Finish and closing the popup (for example, by clicking the X button) are considered successful onboarding. In both scenarios, the exchangeable token code and the session info object containing the customer's asset IDs will be returned. Exiting on the final screen is not considered a cancel event.
{
data: {
phone_number_id: '<CUSTOMER_BUSINESS_PHONE_NUMBER_ID>',
waba_id: '<CUSTOMER_WABA_ID>',
business_id: '<CUSTOMER_BUSINESS_PORTFOLIO_ID>',
<!-- only included if customer selected ad accounts -->
ad_account_ids: ['<CUSTOMER_AD_ACCOUNT_ID_1>', '<CUSTOMER_AD_ACCOUNT_ID_2>'],
<!-- only included if customer selected Facebook Pages -->
page_ids: ['<CUSTOMER_PAGE_ID_1>', '<CUSTOMER_PAGE_ID_2>'],
<!-- only included if customer selected datasets -->
dataset_ids: ['<CUSTOMER_DATASET_ID_1>', '<CUSTOMER_DATASET_ID_2>'],
<!-- only included if customer selected catalogs -->
catalog_ids: ['<CUSTOMER_CATALOG_ID_1>', '<CUSTOMER_CATALOG_ID_2>'],
<!-- only included if customer selected Instagram accounts -->
instagram_account_ids: ['<CUSTOMER_IG_ACCOUNT_ID_1>', '<CUSTOMER_IG_ACCOUNT_ID_2>'],
<!-- only included for multi-WABA flows -->
waba_ids: ['<CUSTOMER_WABA_ID_1>', '<CUSTOMER_WABA_ID_2>']
},
type: 'WA_EMBEDDED_SIGNUP',
event: '<FLOW_FINISH_TYPE>',
}| 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> |
Only included if the customer selected ad accounts during the flow. The business customer's ad account ID. |
4052175343162067 |
<CUSTOMER_PAGE_ID> |
Only included if the customer selected Facebook Pages during the flow. The business customer's Facebook Page ID. |
1791141545170328 |
<CUSTOMER_DATASET_ID> |
Only included if the customer selected datasets during the flow. The business customer's dataset ID. |
524126980791429 |
<CUSTOMER_CATALOG_ID> |
Only included if the customer selected catalogs during the flow. The business customer's catalog ID. |
8827498273649182 |
<CUSTOMER_IG_ACCOUNT_ID> |
Only included if the customer selected Instagram accounts during the flow. The business customer's Instagram account ID. |
1749204838281942 |
<CUSTOMER_WABA_ID> (in waba_ids array) |
Only included for multi-WABA flows. Array of the business customer's WhatsApp Business Account IDs. |
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_OBO_MIGRATION: Indicates user completed an on-behalf-of migration flow.FINISH_GRANT_ONLY_API_ACCESS: Indicates user completed a grant-only API access flow.ERROR: Indicates the user encountered an error during the flow. |
FINISH |
Abandoned flow structure:
{
data: {
current_step: '<CURRENT_STEP>',
},
type: 'WA_EMBEDDED_SIGNUP',
event: 'CANCEL',
}| 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 |
User reported errors
{
data: {
error_message: '<ERROR_MESSAGE>',
error_code: '<ERROR_CODE>',
session_id: '<SESSION_ID>',
timestamp: '<TIMESTAMP>',
},
type: 'WA_EMBEDDED_SIGNUP',
event: 'CANCEL',
}| 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_CODE> |
Error code. Include this value 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 |
Parse this object on your server to extract and capture the customer's phone number ID and WABA ID, or to determine which screen they abandoned. See Abandoned flow screens for a list of possible
<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:
console.log('message event: ', data); // remove after testing
console.log('message event: ', event.data); // remove after testing
These statements just dump the returned phone number and WABA IDs, or the abandoned screen string, to the JavaScript console. You can leave this code in place and keep the console open to easily see what gets returned when you are testing the flow, but you should remove them when you are done testing.
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.
// Response callback
const fbLoginCallback = (response) => {
if (response.authResponse) {
const code = response.authResponse.code;
console.log('response: ', code); // remove after testing
// your code goes here
} else {
console.log('response: ', response); // remove after testing
// your code goes here
}
}
The callback function assigns the exchangeable token code to a
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.
Note that the if-else statement in the code above has two statements that can be used for testing purposes:
console.log('response: ', code); // remove after testing
console.log('response: ', response); // remove after testing
These statements just dump the code or the raw response to the JavaScript console. You can leave this code in place and keep the console open to easily see what gets returned when you are testing the flow, but you should remove them when you are done testing.
Launch method and callback registration
This portion of the code defines a method which can be called by an
onclick event that registers the response callback from the previous step and launches the Embedded Signup flow.Add your configuration ID here.
// Launch method and callback registration
const launchWhatsAppSignup = () => {
FB.login(fbLoginCallback, {
config_id: '<CONFIGURATION_ID>', // your configuration ID goes here
response_type: 'code',
override_default_response_type: true,
extras: {
setup: {},
}
});
}
This portion of the code defines a button that calls the launch method from the previous step when clicked by the business customer.
<!-- Launch button --> <button onclick="launchWhatsAppSignup()" style="background-color: #1877f2; border: 0; border-radius: 4px; color: #fff; cursor: pointer; font-family: Helvetica, Arial, sans-serif; font-size: 16px; font-weight: bold; height: 40px; padding: 0 24px;">Login with Facebook</button>
Testing
Once you have completed all of the implementation steps above, you should be able to test the flow by simulating a business customer while using your own Meta credentials. Anyone who you have added as an admin or developer on your app (in the App Dashboard > App roles > Roles panel) can also begin testing the flow, using their own Meta credentials.
Onboarding business customers
Embedded Signup generates assets for your business customers, and grants your app access to those assets. However, you still need to make a series of API calls to fully onboard new business customers who have completed the flow.
The API calls you must make to onboard customers are different for Solution Partners and Tech Providers/Tech Partners.
Onboarding customers as a Solution PartnerOnboarding customers as a Tech ProviderOnboarding business customers as a Tech Provider or Tech Partner | Developer Documentation
Onboarding business customers as a Tech Provider or Tech Partner
Updated: Nov 14, 2025
This document describes the steps Tech Providers and Tech Partners must perform to onboard new business customers who have completed the Embedded Signup flow.
If you are a Tech Provider or Tech Partner, any business customer who completes your implementation of the Embedded Signup flow will not be able to use your app to access their WhatsApp assets or send and receive messages (if you are offering messaging services) until you complete these steps.
What you will need
Also, if you wish to test messaging capabilities using the customer’s business phone number, you will need a WhatsApp phone number that can already send and receive messages from other WhatsApp numbers.
Perform all of the requests described below using server-to-server requests. Do not use client-side requests.
Step 1: Exchange the token code for a business token
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<APP_ID> |
Required.
Your app ID. This is displayed at the top of the App Dashboard. |
236484624622562 |
<APP_SECRET> |
Required.
Your app secret. You can get this from the App Dashboard > App Secret > Basic panel. |
614fc2afde15eee07a26b2fe3eaee9b9 |
<CODE> |
Required.
The code returned by Embedded Signup when the customer successfully completed the flow. |
|
Response parameters
| Placeholder | Description | Example value |
|---|---|---|
<BUSINESS_TOKEN> |
The customer’s business token. |
|
Step 2: Subscribe to webhooks on the customer’s WABA
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<BUSINESS_TOKEN>String |
Required.
The business customer’s business token. |
|
<WABA_ID>String |
Required.
WhatsApp Business Account ID. |
102290129340398 |
Step 5: Instruct the customer to add a payment method
Instruct your customer to use the WhatsApp Manager to add a payment method. You can provide them with the following Help Center link:
Alternatively, you can instruct them to:
Access the WhatsApp Manager > Overview panel at https://business.facebook.com/wa/manage/home/Click the Add payment method buttonComplete the flow
Once your customer adds a payment method, they are fully onboarded onto the WhatsApp Business Platform and can begin using your app to access their WhatsApp assets and send and receive messages (if you are providing them with that service).
Onboarding business customers as a Solution Partner | Developer Documentation
Onboarding business customers as a Solution Partner
Updated: Nov 14, 2025
This document describes the steps Solution Partners must perform to onboard new business customers who have completed the Embedded Signup flow.
If you are a Solution Partner, any business customer who completes your implementation of the Embedded Signup flow will not be able to use your app to access their WhatsApp assets or send and receive messages until you complete these steps.
What you will need
Also, if you wish to test messaging capabilities using the customer’s business phone number, you will need a WhatsApp phone number that can already send and receive messages from other WhatsApp numbers.
Perform all of the requests described below using server-to-server requests. Do not use client-side requests.
Step 1: Exchange the token code for a business token
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<APP_ID> |
Required.
Your app ID. This is displayed at the top of the App Dashboard. |
236484624622562 |
<APP_SECRET> |
Required.
Your app secret. You can get this from the App Dashboard > App Secret > Basic panel. |
614fc2afde15eee07a26b2fe3eaee9b9 |
<CODE> |
Required.
The code returned by Embedded Signup when the customer successfully completed the flow. |
|
Response parameters
| Placeholder | Description | Example value |
|---|---|---|
<BUSINESS_TOKEN> |
The customer’s business token. |
|
Step 2: Subscribe to webhooks on the customer’s WABA
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<BUSINESS_TOKEN> |
Required.
The customer’s business token. |
|
<WABA_ID> |
Required.
The customer’s WABA ID. |
102290129340398 |
We are currently testing new steps for sharing your credit line with onboarded business customers. These steps will eventually replace this step, so if you wish to implement these steps now, see Alternate method for sharing your credit line.
Note: If you are using the below API i.e.
whatsapp_credit_sharing_and_attach, you would need to add your System User to the shared WhatsApp Business Accounts as a pre-requisite. Please refer to this doc for steps.Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<CUSTOMER_BUSINESS_CURRENCY> |
Required.
The business’s currency, as a three-letter currency code. Support values are: AUDEURGBPIDRINRUSD
This currency is used for invoicing and corresponds to pricing rates. |
USD |
<CUSTOMER_WABA_ID> |
Required.
The customer’s WABA ID. |
102290129340398 |
<EXTENDED_CREDIT_LINE_ID> |
Required.
Your extended credit line ID. |
1972385232742146 |
<SYSTEM_TOKEN> |
Required.
Your system token. |
|
Response parameters
| Placeholder | Description | Example value |
|---|---|---|
<ALLOCATION_CONFIGURATION_ID> |
The extended credit line’s allocation configuration ID.
Save this ID if you want to verify that your credit line has been shared with the customer. |
58501441721238 |
<CUSTOMER_WABA_ID> |
The customer’s WABA ID. |
102290129340398 |
Cloud API flow | Developer Documentation
Cloud API flow
Updated: Nov 11, 2025
This document describes the default screens that your business customers will be presented with as they navigate the Embedded Signup flow. Note that if you inject pre-filled data, you can pre-fill some of these screens, and bypass many of them entirely, reducing the likelihood of errors and making it much easier for your business customers to onboard onto the platform. This is the UI flow for the latest version v4.
Screens
Authentication screen
This screen authenticates business customers using their Facebook or Meta Business Suite credentials.

This screen describes the data the business customer will be permitting your app to access.

Business Asset Selection Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Business Asset Creation Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Phone number addition screen
This screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.
It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.
If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead.

Phone number verification screen
This screen allows the business customer to verify ownership of the business phone number they entered in the previous step.

Permissions review screen
This screen provides a summary of the permissions the business customer will be granting to your app.

Success screen
This screen indicates that Meta successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).
When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform.

Customizing the default flow | Developer Documentation
Customizing the default flow
Updated: Nov 14, 2025
This document provides an overview of the various ways that you can customize Embedded Signup’s default flow to present different versions of the flow to your business customers.
Onboarding WhatsApp Business app users (aka “Coexistence”)
You can configure Embedded Signup to allow business customers to onboard using their existing WhatsApp Business app account and phone number:

Businesses who are successfully onboarded after choosing this option will then be able to use your app to message their customers at scale, but still have the ability to send messages on a one-to-one basis using the WhatsApp Business app.
Pre-filling screens
You can pre-fill many of Embedded Signup’s default flow screens with a business customer’s business data. Pre-filling screens can dramatically reduce the amount of input and interaction required by your customers, and shorten flow.

Bypassing phone number addition and verification
You can customize Embedded Signup to entirely skip the phone number addition and verification screens. This can be useful if you don’t want business customers to have to enter a phone number, retrieve the verification code sent to the number, and then verify the code using the number.


App-Only Install
App-Only Install is a way to configure Embedded Signup so that only business tokens can be used to access assets owned by customers onboarded via the flow. This does not affect the flow itself, only which tokens must be used.
Onboarding WhatsApp Business app users (aka "Coexistence") | Developer Documentation
Onboarding WhatsApp Business app users (aka "Coexistence")
Updated: Mar 20, 2026
You can configure Embedded Signup to allow business customers to onboard using their existing WhatsApp Business app account and phone number. Customers who are successfully onboarded after choosing this option will then be able to use your app to message their customers at scale, but still have the ability to send messages on a one-to-one basis using the WhatsApp Business app, while keeping messaging history between both apps in sync.
How it works
When you configure Embedded Signup for WhatsApp Business app phone numbers, a business customer who goes through the flow will be given the option to connect their existing WhatsApp Business app account to Cloud API:

If they choose this option and enter their WhatsApp Business app phone number, they will be presented a verification code to enter.

The message instructs the business to copy the verification code and follow the steps:

Expect to receive a message from the official Facebook Business Account. Click Connect:

Tap the Connect to the Business Platform button to continue the onboarding process.

Tap the Confirm button in the app to give the business the option to share their chat history with you.

Paste the verification code.

They can complete the remainder of the Embedded Signup flow. This returns their asset IDs and exchangeable token code to the spawning window, as normal. You can then use that information in API calls to (1) onboard the business customer the same way you would any other business customer and (2) synchronize their contacts and messaging history (if permitted by the business) so you can populate it in your app.
Requirements
Limitations
Unsupported countries
WhatsApp Business account phone numbers with country codes from the following countries are not supported:
NigeriaSouth Africa
Pricing
After a business customer has been onboarded to Cloud API, messages sent by the business via the WhatsApp Business app will continue to be free, but messages sent via API will be subject to Cloud API pricing.
See our API Solutions for WhatsApp Business App Users pricing explainer PDF for breakdowns of common pricing scenarios.
Customer service window
Customer service windows will only be opened when a WhatsApp user messages a business customer who is already onboarded onto Cloud API. If a WhatsApp user messages a business just prior to the business being onboarded onto Cloud API, the business can only respond with a template message, since no customer service was opened. If the user messages the business after it has been onboarded onto Cloud API, a customer service window will be opened as normal, and the business can then respond with a non-template message.
The 24-hour customer service window restriction applies to messages sent via Cloud API. Messages sent from the WhatsApp Business app are not subject to the customer service window and do not create, extend, or affect Cloud API conversation windows or Cloud API pricing.
Feature comparison
The following table describes features available to business customers who have been onboarded to Cloud API, as well as any changes to WhatsApp Business app functionality post-onboarding.
| Existing feature on the WhatsApp Business App | Changes to features on the WhatsApp Business App AFTER onboarding to Cloud API | Is the WhatsApp Business app feature supported on Cloud API? |
|---|---|---|
|
Individual (1:1) chats |
Message Edit/Revoke is now supported. |
Supported.
All chat messages in the most recent 6 months can be synchronized.
Messages sent and received are mirrored between the Cloud API and WhatsApp Business app. |
|
Contacts |
No change. |
Supported.
All contacts with a WhatsApp number can be synchronized. |
|
Group chats |
No change. |
Not supported.
Group chats will not be synchronized. |
|
Disappearing messages |
Disappearing messages will be turned off for all individual (1:1) chats |
Not supported. |
|
View once messages will be disabled for all individual (1:1) chats |
Not supported. | |
|
Live location message |
Live location messages will be disabled for all individual (1:1) chats |
Not supported. |
|
Broadcast lists |
Broadcast list will be disabled.
Business will not be able to create new Broadcast Lists.
Existing Broadcast Lists will become read-only. |
Not supported. |
|
Voice and video calls |
No change. |
Not supported. |
|
Business tools (eg. catalog, orders, status) |
No change. |
Not supported. |
|
Messaging tools (e.g., marketing messages, greeting message, away message, quick replies, labels) |
No change. |
Not supported. |
|
Business profile (eg. business name, address, website) |
No change. |
Not supported. |
|
Channels |
No change. |
Not supported. |
Linked devices
Businesses can link up to four WhatsApp “companion” clients to their WhatsApp Business app account on other devices (described as “linked devices” in our Help Center).
All companion clients are supported, except for WhatsApp for Windows and WhatsApp for WearOS.
Once a business customer onboards to Cloud API with an existing WhatsApp Business app account and number, all companion apps will be unlinked from the account, and the business can then re-link any supported companion apps.
WhatsApp users who use an unsupported companion client to message an onboarded business can do so, but the message will not trigger messages webhooks, so the business won’t be able to mirror the message in their own app.
Messages sent from an onboarded business (by any means) that are viewed in an unsupported companion device will appear with placeholder text, instructing the WhatsApp user to view the message in their primary device.
Setting up your app
Step 1: Subscribe to webhooks
Navigate to the App Dashboard > WhatsApp > Configuration panel and subscribe your app to the following WhatsApp Business Account webhook topic fields, and make sure your app’s callback code can digest payloads for each of them. Note that these fields are in addition to any fields you are already subscribed to as a solution provider.
history — describes past messages the business customer has sent/receivedsmb_app_state_sync — describes the business customer’s current and new contactssmb_message_echoes — describes any new messages the business customer sends with the WhatsApp Business app after having been onboarded
Step 2: Customize Embedded Signup
Add a
featureType property set to whatsapp_business_app_onboarding to the extras object in the launch method and callback registration portion of the Embedded Signup implementation code.To verify that you have enabled the feature correctly, access your implementation of Embedded Signup. If the WABA selection screen has been replaced with a screen that gives you the option to connect your existing WhatsApp Business account, the feature is enabled:

Step 3: Surface Embedded Signup to customers
Once you have confirmed that the feature has been enabled, surface Embedded Signup to your business customers.
Note that when a business completes the flow and you onboard the customer, you have 24 hours to synchronize their messaging history, otherwise they must be offboarded and they must complete the flow again. For this reason, we recommend that you:
onboard and synchronize as soon as the business completes the flowinform the business that you are synchronizing their WhatsApp Business app dataadvise them to keep the WhatsApp Business app open to facilitate the synchronization process
Onboarding and synchronization can take several minutes, depending on a number of factors such as the size of the business’s messaging history, their internet speed, how quickly you can digest webhooks, etc.
When you complete the onboarding process, the WhatsApp Business app will automatically refresh and indicate to the business that their number is now connected to the API:

After you finish synchronizing the business’s messaging history, we recommend that you inform the customer that the process is complete.
Onboarding business customers
When a business customer successfully completes the Embedded Signup flow, their asset IDs and an exchangeable token code will be returned to the window that spawned the flow, as normal, but the session event payload will have
event set to FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING:{
data: {
waba_id: "<CUSTOMER_WABA_ID>"
},
type: "WA_EMBEDDED_SIGNUP",
event: "FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING",
version: 3
}Capture the customer’s asset IDs and exchangeable token code and use them to onboard the customer as you normally would, but skip the phone number registration step, as the number is already registered.
Onboarding business customers as a Solution ProviderOnboarding business customers as a Tech Provider
Once you have completed these onboarding steps, you can begin the messaging history synchronization process.
Check onboarding status (optional)
If you wish, you can check if the customer’s business phone number is registered for both Cloud API and WhatsApp Business app use by requesting the
is_on_biz_app and platform_type fields on the business phone number ID:Example request:
Example response:
If
is_on_biz_app is true and platform_type is CLOUD_API, the business phone number is able to use Cloud API and the WhatsApp Business app:Synchronizing WhatsApp Business app data
After you onboard the business customer, you have 24 hours to synchronize their contacts and messaging history, otherwise they must be offboarded and complete the flow again. For this reason, we recommend that you begin the synchronization process as soon as you finish onboarding the business.
As a reminder, make sure that you subscribed to the business’s WABA when you onboarded the business, and that you are subscribed to the additional webhook fields, otherwise you will miss important webhooks.
Step 2: Initiate message history synchronization
Upon success, one or more history webhooks will be triggered, depending on if the business chose to share their messaging history with you.
Note that you can only perform this step once. If you need to perform it again, the customer must first offboard, then complete the Embedded Signup flow again.
Messaging history shared
If the business chose to share their messaging history with you, a series of history webhooks will be triggered, describing each message sent to, or received from, WhatsApp users within a set period of time.
See history for a description of the contents of these webhooks and how they are organized.
Messaging history not shared
If the business chose not to share their messaging history with you, a history webhook with error code
2593109 will be triggered instead.Step 3: Mirror new WhatsApp Business app messages
Onboarded businesses are still able to use the WhatsApp Business app and supported companion devices to send and receive messages. Each time a business sends a message with one of these apps, it triggers an smb_message_echoes webhook, which you must digest and display in the contact message thread history in your app.
Reporting conversion activity
Onboarded business customers may run Click to WhatsApp ads, so we recommend that you report purchase/lead-gen signals on behalf of the business using the Conversions API. See Conversions API for business messaging.
Offboarding business customers
Instead, your business customers can use the WhatsApp Business app to disconnect from Cloud API by navigating to the Settings > Account > Business Platform and clicking the Disconnect Account button. When a business customer disconnects from Cloud API, an account_update webhook with a
PARTNER_REMOVED event is triggered.Errors
If you onboard a business customer with a WhatsApp Business app phone number, you may receive an unsupported messages webhook with error code
First-time messaging: A WhatsApp user messages your business for the first time. This is especially common when users tap one of your ads that click to WhatsApp and immediately send a message. The error typically resolves within a few seconds, after which messages are delivered normally.Unsupported companion device: A WhatsApp user with an unsupported companion device sends or receives a message to or from your business.
131060. This is expected and can occur in the following scenarios:If you receive this webhook, instruct the business to check the WhatsApp Business app for the message.
Need support?
For Coexistence onboarding, choose:
Question Topic: “WABiz: Onboarding” and “TechProvider: Onboarding”Request Type: “Embedded Signup - Coexistence Onboarding”
For Coexistence API issues, choose:
Question Topic: “WABiz: Cloud API”Request Type: “Coexistence Data Synchronization APIs and Webhooks”Pre-filling screens | Developer Documentation
Pre-filling screens
Updated: Nov 10, 2025
If you know details about your customer’s business, such as its name and address, you can inject this data into Embedded Signup. This can pre-fill screens or bypass them altogether, dramatically reducing the amount of input and interaction required by your customers.
For example, here is the business portfolio screen, pre-filled with business’s name, email address, website, country, and a pre-verified business phone number:

We recommend that you inject business portfolio data, a pre-verified number, and phone profile data. Injecting this data provides the best experience for your customer, as it:
entirely pre-fills the business portfolio screenbypasses the WhatsApp Business Account (WABA) selection and creation screensbypasses the business phone number selection and verification screensautomatically sets the business phone number’s profile information in the WhatsApp client
Embedded Signup Integration Helper
The Embedded Signup Integration Helper provides a convenient way for you to create pre-filled data payloads and test their impact on the flow. To access the payload tool:
Navigate to App Dashboard > WhatsApp > Embedded Signup Builder.Locate the Embedded Signup Setup section.Locate the Embedded Signup Pre-fill row.Click the Edit pre-fill data button.
Injecting Data
The
FB.login function, which gets called when a business customer launches Embedded Signup, accepts an object as an argument. Use this object’s extras.setup property to inject data:// Launch method and callback registrationconst launchWhatsAppSignup =()=>{
FB.login(fbLoginCallback,{
config_id:'<CONFIGURATION_ID>',// your configuration ID goes here
response_type:'code',
override_default_response_type:true,
extras:{
setup:{
business:{// Business portfolio data goes here},
preVerifiedPhone:{// Pre-verified phone number IDs go here},
phone:{// Phone number profile data goes here},
whatsAppBusinessAccount:{// WABA IDs go here}},
featureType:'',
sessionInfoVersion:'3',}});}Business portfolio data
You can inject the following business portfolio details into the business portfolio screen:
business portfolio namebusiness portfolio email addressbusiness portfolio websitebusiness portfolio country (as well as additional address details)business phone number
Alternatively, you can inject just an existing business portfolio ID, and its existing details will automatically be injected into the screen. This can be useful if you want a pre-verified phone number to be associated with the customer’s existing business portfolio.
Injecting business portfolio data will pre-fill the business portfolio screen and also cause Embedded Signup to skip the WABA selection and WABA creation screens.

Injecting business phone number data will pre-fill the phone number addition screen:

Note that even if you inject data, the business customer can still edit this data using the Edit button, if they wish.
When a business customer completes the flow, the business portfolio information you injected will be used to create the business customer’s business portfolio and WABA.
Business object syntax
setup: {
business: {
id: <BUSINESS_PORTFOLIO_ID>,
name: '<BUSINESS_PORTFOLIO_NAME>',
email: '<BUSINESS_PORTFOLIO_EMAIL_ADDRESS>',
website: '<BUSINESS_PORTFOLIO_WEBSITE>',
address: {
streetAddress1: '<BUSINESS_PORTFOLIO_STREET_ADDRESS_LINE_1>',
streetAddress2: '<BUSINESS_PORTFOLIO_STREET_ADDRESS_LINE_2>',
city: '<BUSINESS_PORTFOLIO_CITY>',
state: '<BUSINESS_PORTFOLIO_STATE>',
zipPostal: '<BUSINESS_PORTFOLIO_ZIP_CODE>',
country: '<BUSINESS_PORTFOLIO_COUNTRY>'
},
phone: {
code: <BUSINESS_PORTFOLIO_COUNTRY_CALLING_CODE>,
number: '<BUSINESS_PORTFOLIO_PHONE_NUMBER>'
},
timezone: '<BUSINESS_PORTFOLIO_TIME_ZONE>'
}
}Business object parameters
| Placeholder | Description | Example value |
|---|---|---|
<BUSINESS_PORTFOLIO_ID>Integer or null |
Required if using an existing business portfolio, otherwise set to null or omit to create a new portfolio.
Set to the business customer’s existing business portfolio ID if you want to pre-fill the screen with data already set on the business portfolio, or if you want to associate a pre-verified phone number with this portfolio.
If set to a portfolio ID, we will check if the business customer owns the portfolio.
If they own it, we will inject its existing data into the flow and ignore all other business object properties.
If they do not own it, we will inject
business.name, business.email, business.website, and address.country values, if they are all set. If any are not set, the flow will display the default business portfolio screen instead.Set to null (or omit the id property entirely) if you want to create a new business portfolio based on injected business.name, business.email, business.website, and address.country values. |
2729063490586005 |
<BUSINESS_PORTFOLIO_NAME>String |
Required if creating a new business portfolio.
Business portfolio name.
If this name matches the name of an existing business portfolio owned by the business customer, the existing portfolio will be used instead (it will be treated as if you assigned the existing portfolio’s ID to the
id property).This name will also be used as the WhatsApp Business Account name, which is only visible in the WhatsApp Manager.
Maximum 100 characters. |
Wind & Wool |
<BUSINESS_PORTFOLIO_EMAIL_ADDRESS>String |
Required if creating a new business portfolio.
The business’s email address.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
support@windandwool.com |
<BUSINESS_PORTFOLIO_COUNTRY_CALLING_CODE>Integer |
Required if injecting a business phone number.
Business phone number country calling code. |
1 |
<BUSINESS_PORTFOLIO_PHONE_NUMBER>String |
Required if injecting a business phone number.
Business phone number, without country calling code. |
6505559999 |
<BUSINESS_PORTFOLIO_WEBSITE>String |
Required if creating a new business portfolio.
The business’s website URL.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
https://windandwool.com/ |
<BUSINESS_PORTFOLIO_STREET_ADDRESS_LINE_1>String |
The business’s street address, line 1.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
1 Hacker Way |
<BUSINESS_PORTFOLIO_STREET_ADDRESS_LINE_2>String |
The business’s street address, line 2.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
Suite 1 |
<BUSINESS_PORTFOLIO_CITY>String |
The business’s city address.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
Menlo Park |
<BUSINESS_PORTFOLIO_STATE>String |
The business’s state address.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
California |
<BUSINESS_PORTFOLIO_ZIP_CODE>String |
The business’s zip code address.
This information will appear in the Meta Business Suite > Business portfolio > Settings > Business info panel. |
94025 |
<BUSINESS_PORTFOLIO_COUNTRY>String |
Required if creating a new business portfolio.
Business address ISO 3166-1 alpha-2 country code. |
US |
<BUSINESS_PORTFOLIO_TIME_ZONE>String |
The business’s time zone in UTC offset format. |
UTC-07:00 |
Example Business Object
setup:{
business:{
name:'Wind & Wool',
email:'support@windandwool.com',
website:'https://windandwool.com/',
address:{
streetAddress1:'1 Hacker Way',
streetAddress2:'Suite 1',
city:'Menlo Park',
state:'California',
zipPostal:'94025',
country:'US'},
phone:{
code:1,
number:'6505559999'},
timezone:'UTC-07:00'}}Pre-verified phone numbers
You can inject a pre-verified business phone number ID into Embedded Signup, which will cause Embedded Signup to skip the phone number addition and phone number verification screens.
If you are injecting a pre-verified phone number along with business portfolio data (either creating a new portfolio or using an existing one), the business portfolio screen will be pre-filled with the pre-verified number:

If you are not injecting business portfolio data along with a pre-verified number ID, the number will appear in the WABA selection screen:

PreVerifiedPhone object syntax
setup: {
preVerifiedPhone: {
ids: [
'<PRE-VERIFIED_PHONE_NUMBER_ID>'
]
}
}Replace
<PRE-VERIFIED_PHONE_NUMBER_ID> with a unique, pre-verified business phone number ID.Note that although the
ids value accepts an array of strings, if you include more than one pre-verified business phone number ID, only the first ID in the array will appear in the WABA selection screen.Phone profile data
You can inject the following phone number profile data. This data does not pre-fill any Embedded Signup screens, but it does populate the business phone number’s profile in the WhatsApp client, which is visible to WhatsApp users.
Phone number profile display namePhone number categoryPhone number description

If you do not include this data, the category will be set to Other, and the business customer must set or edit their profile data on their own.
Phone object syntax
setup: {
phone: {
displayName: '<PHONE_PROFILE_DISPLAY_NAME>',
category: '<PHONE_PROFILE_DISPLAY_CATEGORY>',
description: '<PHONE_PROFILE_DISPLAY_DESCRIPTION>'
}
}Phone object parameters
| Placeholder | Description | Example value |
|---|---|---|
<PHONE_PROFILE_DISPLAY_NAME>String |
Required.
Business profile display name, visible to WhatsApp users in the WhatsApp client (see screenshot above). |
Wind & Wool |
<PHONE_PROFILE_DISPLAY_CATEGORY>String |
Required.
Business profile display category. |
APPAREL |
<PHONE_PROFILE_DISPLAY_DESCRIPTION>String |
Required.
Business phone number profile description. Maximum 512 characters.Rendered emojis are supported however their unicode values are not. Emoji unicode values must be Java- or JavaScript-escape encoded.Hyperlinks can be included but will not render as clickable links.Markdown is not supported. |
Bespoke artisan apparel and lifestyle goods from upcoming designers. |
Example phone object
setup:{
phone:{
displayName:'Wind & Wool',
category:'APPAREL',
description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}}WhatsApp Business Accounts
If you are injecting a pre-verified phone number, you can also include a WABA ID. This will associate the pre-verified number with the existing WABA instead of with a new one that the business customer would be prompted to create as part of the flow.
WhatsAppBusinessAccount object syntax
setup: {
whatsAppBusinessAccount: {
ids: '<WABA_ID>'
}
}Replace
<WABA_ID> with a unique WABA ID.Example whatsAppBusinessAccount object
This example associates a pre-verified phone number with an existing WABA.
setup:{
preVerifiedPhone:{
ids:['106540352242922']},
whatsAppBusinessAccount:{
id:['432428883295692']}}Examples
New business portfolio, pre-verified number, and display profile
// Launch method and callback registrationconst launchWhatsAppSignup =()=>{
FB.login(fbLoginCallback,{
config_id:'31602279155865',
response_type:'code',
override_default_response_type:true,
extras:{
setup:{
business:{
name:'Wind & Wool',
email:'support@windandwool.com',
website:'https://windandwool.com/',
address:{
streetAddress1:'1 Hacker Way',
streetAddress2:'Suite 1',
city:'Menlo Park',
state:'California',
zipPostal:'94025',
country:'US'},
phone:{
code:1,
number:'6505559999'},
timezone:'UTC-07:00'},
preVerifiedPhone:{
ids:['106540352242922']},
phone:{
displayName:'Wind & Wool',
category:'APPAREL',
description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}},
featureType:'',
sessionInfoVersion:'3',}});}Existing business portfolio, pre-verified number, and display profile
// Launch method and callback registrationconst launchWhatsAppSignup =()=>{
FB.login(fbLoginCallback,{
config_id:'31602279155865',
response_type:'code',
override_default_response_type:true,
extras:{
setup:{
business:{
id:'2729063490586005'},
preVerifiedPhone:{
ids:['106540352242922']},
phone:{
displayName:'Wind & Wool',
category:'APPAREL',
description:'Bespoke artisan apparel and lifestyle goods from upcoming designers.'}},
featureType:'',
sessionInfoVersion:'3',}});}Pre-verified phone numbers | Developer Documentation
Pre-verified phone numbers
Updated: Dec 12, 2025
This document explains how to offer your business customers pre-verified business phone numbers. Pre-verified business phone numbers are WhatsApp business phone numbers that have already been verified by you, eliminating the need for customers to have to contact you for a one-time password.

Note that pre-verified business phone numbers are represented by WhatsApp Business Pre-Verified Phone Number objects, which are temporary. When a business customer selects one of these numbers and completes the Embedded Signup flow, the temporary object will be replaced by a valid WhatsApp Business Phone Number object. You must get this new object's ID and use it to register the number within 90 days.
Requirements
Limitations
verification_expiry_time field.If you add a phone number to your pool of pre-verified business phone numbers (Step 1) but do not verify it within 90 days (Step 3), it will be removed from your pool and you will have to add it again.Once a business customer claims a pre-verified business phone number, you have 90 days to register it.
Displaying pre-verified numbers in Embedded Signup
You can display pre-verified business phone numbers in the Embedded Signup flow using pre-filled form data. To do this, add a
preVerifiedPhone object with an ids property to the setup object and assign the IDs of your pre-verified business phone numbers as an array of strings to the ids property:{
scope: '<SCOPE>',
extras: {
feature: '<FEATURE>',
setup: {
preVerifiedPhone: {
ids: [<IDS>]
}
}
}
}For example:
{
scope: 'business_management,whatsapp_business_management',
extras: {
feature: 'whatsapp_embedded_signup',
version: 2,
setup: {
business: {
name: 'Acme Inc.',
email: 'johndoe@acme.com',
phone: {
code: 1,
number: '6505551234'
},
website: 'https://www.acme.com',
address: {
streetAddress1: '1 Acme Way',
city: 'Acme Town',
state: 'CA',
zipPostal: '94000',
country: 'US'
},
timezone: 'UTC-08:00'
},
phone: {
displayName: 'Acme Inc.',
category: 'ENTERTAIN',
description: 'Gears and widgets'
},
preVerifiedPhone: {
ids: ['106540352242922','105954558954427']
}
}
}
}Note that if a pre-verified business phone number with a status of
VERIFIED is not claimed within 90 days of verification, its status will be set to UNVERIFIED but it will still appear in the Embedded Signup flow. If a business customer attempts to claim an unverified number, they must complete verification on their own, which means they must request a one-time password from you.To prevent this experience, we recommend that you keep track of when you verified a number and re-verify it before it reverts to an unverified state.
If you don't know when you last verified a given pre-verified business phone number, request the
code_verification_time and verification_expiry_time fields on the pre-verified business phone number ID. These fields indicate its most recent verification time and its verification expiration time.Determining if a number has been claimed through Embedded Signup
Getting and registering claimed phone numbers
Once a business customer claims a pre-verified business phone number, it will be replaced with a verified WhatsApp business phone number (a WhatsApp Business Phone Number object with a
code_verification_status set to VERIFIED).You will have 90 days to register this number using its ID. If you do not register it within this time frame, it will revert to an
UNVERIFIED status and you will have to request a new verification code and use the code to verify the WhatsApp business phone number again.Getting claimed numbers via session logging
If you are using session logging, the ID will be returned in a message event and captured by your event listener. Send this ID to your server and then use it to register the WhatsApp business phone number.
Getting claimed numbers via API
Parse for the
display_phone_number property on each object returned in the result set. If an object in the result set has a display_phone_number value that matches a number you used to create a pre-verified business phone number, the object represents the WhatsApp business phone number that has replaced the pre-verified business phone number. Copy this object's ID and use it to register the WhatsApp business phone number.Alternatively, you can use the same endpoint with
field expansion to request the display_phone_number field and specify the display phone number. For example:Get pre-verified business phone numbers
Results are automatically sorted in order of creation time. You can also use field expansion to request the
code_verification_status field to have the API only return pre-verified business phone numbers with the indicated verification state:Registering pre-verified numbers programmatically
If you have customized Embedded Signup to bypass the phone number addition screen, you can register pre-verified business phone numbers on an onboarded business customer's WhatsApp Business Account programmatically. To do this, first complete all of the steps to create a pre-verified number, then use the pre-verified number ID to complete Step 1 and Step 4 in the Register Phone Numbers document.
Bypassing the phone number addition screen | Developer Documentation
Bypassing the phone number addition screen
Updated: Nov 14, 2025
This document describes how to customize Embedded Signup to bypass the phone number addition screen (shown below) and phone number verification screen.

If you don’t want your business customers to have to enter or choose a business phone number in the phone number addition screen, you can customize Embedded Signup to skip the screen entirely. However, after a customer successfully completes the customized flow, you must programmatically create and register their business phone number, or build a UI in your app that allows them to do this.
Enabling the feature
To enable this feature, set
featureType to only_waba_sharing in the launch method and callback registration portion of the Embedded Signup code:// Launch method and callback registrationconst launchWhatsAppSignup =()=>{
FB.login(fbLoginCallback,{
config_id:'<CONFIGURATION_ID>',// your configuration ID goes here
response_type:'code',
override_default_response_type:true,
extras:{
setup:{},
featureType:'only_waba_sharing',// set to only_waba_sharing
sessionInfoVersion:'3',}});}When a business customer successfully completes the flow, the session logging message event will have
event set to FINISH_ONLY_WABA:{
data: {
phone_number_id: "<CUSTOMER_BUSINESS_PHONE_NUMBER_ID>",
waba_id: "<CUSTOMER_WABA_ID>"
},
type: "WA_EMBEDDED_SIGNUP",
event: "FINISH_ONLY_WABA",
version: 3
}Website field optional | Developer Documentation
Website field optional
Updated: Nov 4, 2025
This feature is currently only available to approved Select Solution and Premier Solution Partners. See our Sign up for partner-led business verification? Help Center article to learn how to request approval.
By default, the website field is required in the business portfolio screen. If you have been approved for Partner-led Business Verification however, the website field will become optional and will be accompanied by a My business does not have a website or profile page checkbox:

When a business customer checks this box and completes the flow, the customer's WhatsApp assets and exchangeable token code will be generated and returned in a message event and JavaScript response, as usual.
However, the account_update webhook that's triggered when the customer completes the flow will have
event set to PARTNER_CLIENT_CERTIFICATION_NEEDED, which indicates that you must verify their business as part of the onboarding process.Onboard the customer as you normally would, and when you're done, complete the steps described in our Partner-led Business Verification document to verify their business. The customer will not be able to send messages until their business is verified.
Note that if you are unable to verify your customer's business, the customer must first add a website on their own using Meta Business Suite > Settings > Business info?, or they won't be able to send messages. Once they have added a website and it has been accepted, they can also verify their business? on their own, if they choose to do so.
Hosted Embedded Signup | Developer Documentation
Hosted Embedded Signup
Updated: Nov 4, 2025
If you don’t want to implement Embedded Signup by adding JavaScript code to your website or customer portal, you can instead use a link that, when clicked, displays a web page describing onboarding steps, and a button that launches the Embedded Signup flow:

Limitations
Hosted Embedded Signup (“Hosted ES”) can only be used to onboard business customers to Cloud API, and the flow cannot be customized.
Requirements
You will also need:
Your system token.Your app secret.
Step 1: Create a Facebook Login for Business configuration
If you don’t already have a Facebook Login for Business configuration, you must create one. 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 and click the + Create configuration button to access the configuration flow.
Use a name that will help you differentiate this configuration from any others you may create in the future. When completing the flow, be sure to select the WhatsApp Embedded Signup login variation:

When choosing assets and permissions, select only those assets and permissions that you will actually need from your business customers.

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.
Step 2: Get the Hosted ES URL
Navigate to the WhatsApp > Quickstart panel and click the View onboarding button.

Locate the Zero integration onboarding card. The URL displayed in the card is the onboarding page URL:

Click the Copy button to copy the URL to your clipboard. Map this URL to a button on your website or customer portal that, when clicked, opens the URL in a new browser window.
To see what this looks like, you can load the URL in a new browser window or tab, or click the blue “new window” icon, which does the same thing.
This onboarding page looks like this:

Click the Get started button. This is the flow that business customers who click the button on your website or customer portal will see. Complete the flow if you wish.
Step 3: Capture customer asset IDs
Step 4: Generate an HMAC-SHA256 hash
Generate an HMAC-SHA256 hash of your app secret and system token.
Bash example for Linux and macOS
echo -n "<SYSTEM_TOKEN>" | openssl dgst -sha256 -hmac "<APP_SECRET>"
<SYSTEM_TOKEN> — Your system token.<APP_SECRET> — Your app secret (App Dashboard > App settings > Basic)
Step 5: Get a business token
Step 7: Onboard the customer
Onboard the business customer by completing the steps in the appropriate onboarding guide below:
Onboarding business customers as a Tech Provider or Tech Partner (skip step 1)Onboarding business customers as a Solution Partner (skip step 1)Automatic Events API | Developer Documentation
Automatic Events API
Updated: Nov 18, 2025
Business customers who access Embedded Signup can opt in to automatic event identification:

If a business customer opts in, Meta use a combination of regex and natural language processing to analyze the customer’s new message threads originating from Click-to-WhatsApp ads. If our analysis determines that a lead gen or purchase event occurred, an automatic_events webhook is triggered, describing the event. You can then report the event for the customer using the Conversions API so the customer can use it on a Meta surface (in 2026, see Limitations below).
To learn more about how this feature works, see these additional resources.
Limitations
Requirements
Enabling and disabling via Meta Business Suite
Business customers who have already been onboarded via Embedded Signup can enable automatic event identification using Meta Business Suite.

If a business customer who you have already onboarded wants to enable this feature, you can send them these instructions:
Versions | Developer Documentation
Versions
Updated: Dec 11, 2025
The latest Embedded Signup Version is:
v4This guide provides an overview on versioning in Embedded Signup. The versioning cadence will align with Graph API. The versions are not exclusive, partners can gradually roll out a new version of ES to reduce risk. The Embedded Signup version is determined inside of the extras object of the implementation code.
Note: The refreshed UI, currently available in the public preview, will be rolled out to all versions of Embedded Signup in early September.
Available ES Versions
| Version | Date Introduced | Available Until |
|---|---|---|
|
October 8th, 2025 |
TBD | |
|
August 14, 2025 |
October, 2026 | |
|
August 14, 2025 |
October, 2026 | |
|
May 29, 2025 |
October, 2026 | |
|
v2 |
January 2023 |
October, 2026 |
Overview of feature availability
| Version | Feature types | Features | Completion State | Prefilled Info | Session Info Logging | Products (via login config) |
|---|---|---|---|---|---|---|
v4 |
whatsapp_business_app_onboarding |
app_only_install |
Users can finish with a verified, unverified or no phone number |
Can fill business information, no screens will be skipped. |
Sent back for all flows |
Marketing Messages API for WhatsApp(MM API for WhatsApp)
Click to WhatsApp Ads (CTWA)
Conversions API (WhatsApp) |
v3-public-preview |
whatsapp_business_app_onboarding |
app_only_installmarketing_messages_lite |
Users can finish with a verified, unverified or no phone number |
Can fill business information, no screens will be skipped. |
Sent back for all flows |
Not supported |
v2-public-preview |
only_waba_sharingwhatsapp_business_app_onboardingmarketing_messages_lite |
app_only_installmarketing_messages_lite |
Users will finish with a verified phone number |
Can fill business information, no screens will be skipped. |
Sent back for all flows |
Not supported |
v3 |
whatsapp_business_app_onboarding |
app_only_installmarketing_messages_lite |
Users can finish with a verified, unverified or no phone number |
Can fill business information, no screens will be skipped. |
Sent back for all flows |
Not supported |
v2 |
only_waba_sharingwhatsapp_business_app_onboardingmarketing_messages_lite |
marketing_messages_lite |
Users will finish with a verified phone number |
Can fill business information and skip screens |
Partners are required to add a sessionInfoVersion to receive the callback |
Not supported |
Version 4
Released: October 8, 2025 | Detailed changes
Login Configuration
Extras Configuration
extras:{}// The extras object is purposely empty for v4.To use v4: You need to create a new Facebook Login for Business Configuration, and select your desired products. Selecting the products will automatically set you to v4.
Version 3 Public Preview
Released: August 14, 2025 | Available until: October, 2026 | Detailed changes
Extras Configuration
extras:{
setup:"<SETUP_DATA>",
features:[{
name:"<FEATURE_NAME>"}],
featureType:"<FEATURE_TYPE>",
version:"<VERSION>"}| Placeholder | Description | Example Value |
|---|---|---|
<PREFILL_DATA> |
Prefilled business data to inject data into Embedded Signup. |
|
<FEATURE_NAME> |
Indicates a flow or feature to enable. |
Possible Values:
app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT)marketing_messages_lite - Enables the Marketing Messages API for WhatsApp onboarding flow. |
<FEATURE_TYPE> |
Indicates a flow or feature to enable. |
Possible Values:
whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow.Leave blank to enable the default onboarding flow. |
<VERSION> |
Indicates Embedded Signup version flow. |
Possible Values:
v3-public-preview, v2-public-preview, v3, v2 |
Version 2 Public Preview
Released: August 14, 2025 | Available until: October, 2026 | Detailed changes
Extras Configuration
extras:{
setup:"<SETUP_DATA>",
features:[{
name:"<FEATURE_NAME>"}],
featureType:"<FEATURE_TYPE>",
sessionInfoVersion:"<SESSION_INFO_VERSION>"
version:"<VERSION>"}| Placeholder | Description | Example Value |
|---|---|---|
<PREFILL_DATA> |
Prefilled business data to inject data into Embedded Signup. |
|
<FEATURE_NAME> |
Indicates a flow or feature to enable. |
Possible Values:
app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT)marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. |
<FEATURE_TYPE> |
Indicates a flow or feature to enable. |
Possible Values:
whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow.only_waba_sharing - Enables the WhatsApp Business App phone number onboarding custom flow. Will NOT show the new consolidated UI.marketing_messages_lite - Enables the MM API for WhatsApp onboarding custom flow. Will NOT show the new consolidated UI.Leave blank to enable the default onboarding flow. |
<SESSION_INFO_VERSION> |
Indicates the returned session payload. |
Possible Values:
3 |
<VERSION> |
Indicates Embedded Signup version flow. |
Possible Values:
v3-public-preview, v2-public-preview, v3, v2 |
Version 3
|
Released: May 29, 2025 |
Available until: October, 2026 |
Extras Configuration
extras:{
setup:"<SETUP_DATA>",
features:[{
name:"<FEATURE_NAME>"}],
featureType:"<FEATURE_TYPE>",
version:"v3"}| Placeholder | Description | Example Value |
|---|---|---|
<PREFILL_DATA> |
Prefilled business data to inject data into Embedded Signup. |
|
<FEATURE_NAME> |
Indicates a flow or feature to enable. |
Possible Values:
app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT)marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. |
<FEATURE_TYPE> |
Indicates a flow or feature to enable. |
Possible Values:
whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow.Leave blank to enable the default onboarding flow. |
<VERSION> |
Indicates Embedded Signup version flow. |
Possible Values:
v3-public-preview, v2-public-preview, v3, v2 |
Version 2
|
Released: January 2023 |
Available until: October, 2026 |
Extras Configuration
extras:{
setup:"<SETUP_DATA>",
features:[{
name:"<FEATURE_NAME>"}],
featureType:"<FEATURE_TYPE>",
sessionInfoVersion:"<SESSION_INFO_VERSION>",}Head to the pre-fill screens page to see how to inject customer business data into Embedded Signup.
| Placeholder | Description | Example Value |
|---|---|---|
<PREFILL_DATA> |
Prefilled business data to inject data into Embedded Signup. |
|
<FEATURE_NAME> |
Indicates a flow or feature to enable. |
Possible Values:
app_only_install - Allows partners to access WABAs via API using a granular token (BISU), without creating a (SUAT)marketing_messages_lite - Enables the MM API for WhatsApp onboarding flow. |
<FEATURE_TYPE> |
Indicates a flow or feature to enable. |
Possible Values:
whatsapp_business_app_onboarding - Enables the WhatsApp Business App phone number onboarding custom flow.only_waba_sharing - Enables the WhatsApp Business App phone number onboarding custom flow.marketing_messages_lite - Enables the MM API for WhatsApp onboarding custom flow.Leave blank to enable the default onboarding flow. |
<SESSION_INFO_VERSION> |
Indicates the returned session payload. |
Possible Values:
3 |
<VERSION> |
Indicates Embedded Signup version flow. |
Possible Values:
v3-public-preview, v2-public-preview, v3, v2 |
Version 4 | Developer Documentation
Version 4
Updated: Dec 12, 2025
Release date: October 8, 2025. Check back soon for updates on additional supported products.
To upgrade to the v4 experience: You need to create a new Facebook Login for Business Configuration, and select your desired products. Selecting the products will automatically set you to v4.
See screenshots below.
Overview of v4 changes
Learn more
Supported products
v4 supports additional business messaging products, ensuring businesses to set up and manage multiple communication channels from a single platform:
All other supported products
v4 continues to support existing business messaging products, allowing businesses to seamlessly manage their established communication channels.
feature_type parameter.Partner-led Business Verification (PLBV) support: PLBV enables partners to verify business after onboarding via Embedded Signup. If you are considering this option, ensure you are an approved Select Solution or Premier Solution Partner, and approved for access.Automatic Events API: Automatic Events API notifies your application about key events that occur through Click-to-WhatsApp ads.Use the Facebook Login for Business Configuration to get started with v4
v4 enables you to easily set up and change which products you want to include in your onboarding flow:
Step 1: Navigate to App Dashboard > Facebook Login for Business > Configurations to create a new configuration.
Step 2: Select Embedded Signup as the login variation.

Step 3: Select which products you want to include in your onboarding flow. Selecting more than one product is optional.

Step 4: Copy the configuration id to use inside the Facebook Login SDK.

Required assets and permissions
When selecting products for v4, the flow will automatically select all necessary permissions and assets. You will need advanced access for all permissions automatically selected in the flow. If needed, you can select additional assets and permissions. The table below is a reference on what assets and permissions you need depending on what product you would like to offer.
| Product | Required assets | Required permissions (Advanced Access) |
|---|---|---|
WhatsApp Business accounts | whatsapp_business_management whatsapp_business_messaging | |
WhatsApp Business accounts Facebook Pages Ad accounts | ads_read ads_management pages_manage_ads pages_read_engagement pages_show_list | |
Facebook Pages Ad accounts | ads_management pages_manage_ads pages_read_engagement pages_show_list | |
Facebook Pages Ad accounts Instagram accounts | ads_management pages_manage_ads pages_read_engagement pages_show_list | |
WhatsApp Business accounts | whatsapp_business_management whatsapp_business_messaging | |
WhatsApp Business accounts Pixels | whatsapp_business_manage_events | |
Facebook Pages Ad accounts Pixels | page_events | |
Facebook Pages Ad accounts Instagram accounts Pixels | instagram_manage_events |
Version 3 | Developer Documentation
Version 3
Updated: Dec 11, 2025
We are introducing versioning cadence to Embedded Signup that will align with Graph API. v3 will be released on May 29th for all partners to adopt, which will include the following changes.
Business customers can now complete the flow without a phone number
Previously in v2, you would always be required to register a verified phone number (unless partners enabled the bypass phone numbers flow) to complete the flow. You can now complete the flow with statuses like verified, unverified, or no phone number at all. You can either go through Embedded Signup again, go on WhatsApp manager, or the partner can utilize API calls to verify the number.
To determine the status of the phone number, visit the documentation on session info logging.
Session Info Logging is automatically enabled
All partners who are on v3 will have session info logging enabled automatically. Partners will still have to add an event listener on the same window of Embedded Signup to process the incoming information.
Adding the features property in the configuration
You can now utilize the features property to enable a range of features in Embedded Signup. The property allows you to add multiple features instead of just one in the featureType property from v2.
v3 request syntax
// Launch method and callback registration
const launchWhatsAppSignup = () => {
FB.login(fbLoginCallback, {
config_id: '<CONFIGURATION_ID>', // your configuration ID goes here
response_type: 'code',
override_default_response_type: true,
extras: {
version: 'v3'
setup: {},
features: [<FEATURE_NAME>],
featureType: '<FEATURE_TYPE>'
}
}| Placeholder | Description | Example |
|---|---|---|
<FEATURE_NAME> |
Name of feature to enable in ES configuration.
Note: You can leave the value blank to follow the default flow.
Values can be: app_only_install — Allows partners to only access WABAs via API using a business token.marketing_messages_lite — Enables the MM API for WhatsApp onboarding flow. |
{
features: [
{
name: 'marketing_messages_lite'
}
]
} |
<FEATURE_TYPE> |
Name of feature types to enable in ES configuration.
Value can only be whatsapp_business_app_onboarding, which enables the WhatsApp Business App phone number onboarding custom flow. |
whatsapp_business_app_onboarding |
Removal of multiple featuretype options in the ES Configuration
In v2, business customers enabling a custom flow would be required to complete the embedded sign up multiple times depending on the number of featureTypes added to the configuration.
Removing only_waba_sharing
The bypass phone number screen flow allows for a streamlined onboarding process where the WABA is shared without the need to go through the phone number setup steps. This flow will no longer be supported in v3. If you want to use the flow, use v2.
Removing marketing_messages_lite
Marketing Messages API for WhatsApp will still be supported through the features argument. If you would still like to use the flow, update your configuration to the following.
Removing coexistence
To launch the WhatsApp Business App Onboarding flow, partners will have to use
whatsapp_business_app_onboarding instead of coexistence.Embedded Signup Pre-Filled will no longer skip screens.
Partners will still be able to pre-fill business information in Embedded Signup, but the business customer will not have the option to bypass any screens in the flow. For partners who would still like to use the flow, you should stick to using v2.
Measurement Partners must remain on v2
Please note that Measurement product onboarding will only be supported on v2 for the time being. Continuing to support Measurement partners is important and will be supported in a future version.
Version 3 Public Preview | Developer Documentation
Version 3 Public Preview
Updated: Nov 4, 2025
We are updating the UI for Embedded Signup. You can get a preview of what it looks like by enabling v3-public-preview. The new version will give partners a preview on what’s to come for Embedded Signup in the near future. Functionality between v3-public-preview and v3 are identical; the key difference is a simplified UI on v3-public-preview.
Authentication screen
This screen authenticates business customers using their Facebook or Meta Business Suite credentials.

This screen describes the data the business customer will be permitting your app to access.

Business Asset Selection Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Business Asset Creation Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Phone number addition screen
This screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.
It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.
If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead.

Phone number verification screen
This screen allows the business customer to verify ownership of the business phone number they entered in the previous step.

Permissions review screen
This screen provides a summary of the permissions the business customer will be granting to your app.

Success screen
This screen indicates that we successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).
When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform.

Version 2 Public Preview | Developer Documentation
Version 2 Public Preview
Updated: Nov 4, 2025
We are updating the UI for Embedded Signup. You can get a preview of what it looks like by enabling v2-public-preview. The new version will give partners a preview on what’s to come for Embedded Signup in the near future. Functionality between v2-public-preview and v2 are identical; the key difference is a simplified UI on v2-public-preview.
Authentication screen
This screen authenticates business customers using their Facebook or Meta Business Suite credentials.

This screen describes the data the business customer will be permitting your app to access.

Business Asset Selection Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Business Asset Creation Screen
This screen gives customers the option to select existing business assets such as a Meta business portfolio and WhatsApp Business Account.
Users also have the option to create new assets if they have not reached their portfolio limit.

Phone number addition screen
This screen allows the business customer to enter a new business phone number to associate with their WhatsApp Business Account.
It also allows the customer to choose how they wish to receive their verification code, which they will need to provide in the next step.
If you are providing phone numbers to your customers, you will have to deliver these codes to your customers, or provide pre-verified numbers instead.

Phone number verification screen
This screen allows the business customer to verify ownership of the business phone number they entered in the previous step.

Permissions review screen
This screen provides a summary of the permissions the business customer will be granting to your app.

Success screen
This screen indicates that we successfully created and associated all of the business customer’s assets (business portfolio, WABA, phone number display profile, and business phone number).
When the customer clicks Finish, a message event will be triggered, containing the customer’s WABA ID and business phone number ID, which you must then use to onboard the customer to the platform.

App-Only Install | Developer Documentation
App-Only Install
Updated: Nov 4, 2025
You can configure Embedded Signup so that only business tokens can be used to access assets owned by customers onboarded via the flow. This approach offers enhanced security by reducing risk associated with system tokens, flexibility in simplifying onboarding for other Meta assets, and scalability to support a larger number of onboardings. By using a granular token, you can also reduce the negative impact in case of a compromised token, making it a more secure and efficient way to manage your business customer assets.
Note that App-Only Install can't be used to onboard WhatsApp Business app users.