Embedded Signup

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:
authenticate their identity using their Facebook or Meta Business Credentialsaccept terms of service for Cloud API, WhatsApp Business, Meta, Marketing Messages Lite API and Meta Business Tool Termsselect multiple WhatsApp APIs and accept terms of servicegrant your app access to their WhatsApp assetsselect an existing business portfolio or create a new oneselect an existing WhatsApp Business Account (WABA) or create a new oneenter and verify their business phone number (their own, or one you have provided)enter a display name that can appear in place of their number in the WhatsApp client
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:
exchange the code for a customer-scoped business tokenregister the customer’s business phone number for Cloud API usesubscribe your app to webhooks on the customer’s WABAshare your credit line with the customer (Solution Partners only)
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:
    Business verificationResolving integrity issues and accessing Business Support HomeSending the first message via a partner solutionSending business-initiated messages using templates

    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

    Business phone numbers can only be registered for use with Cloud API.Business phone numbers already in use with the WhatsApp Business app are supported, but require you customize the flow to enable WhatsApp Business app user onboarding (aka “Coexistence”).Business customers onboarded via Embedded Signup start with default messaging 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:
    whatsapp_business_management — necessary if your app needs access to onboarded customer WhatsApp Business Account settings and message templates.whatsapp_business_messaging — necessary if your app needs access to onboarded customer business phone number settings, or if your app will be used by customers to send and receive messages.
    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

    Sandbox accounts are valid for 30 days, after which they will be deactivated and must be reclaimed in order to be used again.The sandbox account cannot be used to create additional sandbox business portfolios, WABAs, or business phone numbers; the assets are generated automatically and will appear in the Embedded Signup flow.The sandbox account is associated with the app’s admin. In order for the sandbox account’s assets to appear in the Embedded Signup flow, the app admin must be signed into their Meta developer account.The sandbox account’s business portfolio will not appear in the Meta Business Suite or WhatsApp ManagerYou can exchange the returned token code for the sandbox account’s business token and use it to get data on the account’s WABA ID, but the business phone number cannot be used to send or receive messages.

    Claiming sandbox accounts

    To claim your sandbox account:
      Navigate to the App Dashboard > WhatsApp > Quickstart panel.Locate the Testing Integrations section.Click the Claim sandbox account button.

      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:
        Navigate to the App Dashboard > WhatsApp > Quickstart panel.Locate the Testing Integrations section, then locate your sandbox account.Click your sandbox account’s Delete account button.

        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:
        Have a US country calling code (+1)Have a 555 area codeAre verified automaticallyCannot be migrated to another WhatsApp Business Account, or used outside of the WhatsApp Business platform
        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:
        launch Embedded Signup in various flow configurationssee data that gets returned when a business customer completes the flowgenerate implementation code and onboarding queries, which you can copy and paste into your website, business customer portal, and serversend API queries to endpoints you will need to use when onboarding customers who complete the flow
        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

        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 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: {},
            }
          });
        }
        

        Launch button

        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 Provider

        Onboarding 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

        the business customer’s WABA ID (returned via session logging or API request)the business customer’s business phone number ID (returned via session logging or API request)your app ID (displayed at the top of the App Dashboard)your app secret (displayed in the App Dashboard > App settings > Basic panel)
        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.
        AQBhlXsctMxJYbwbrpybxlo9tLPGy-QAmjBJA03jxLos43wxlBlrYozY5C33BXJULd133cOJf_5y6EkJZYMrAmW-EMj3Wdap9-NUM2nS4s8tC-ES7slBhh6QpCFM7-SzpI-iqsjqTGyxbUUW3AeaEyLkeZFIkBgcQ_SOxo9HShm20SDR5_n7AT9ZJ5dcgpqBQykNT-pQ8V7Ne9-sr6RLAWtJMF7-Zx6ABudRcWIN53tUTtquDVNuq3lrco4BlVQAv-54tR83Ae0ODN9Uet6j-BVLuetXhQCM3sz9RdgedlbxkidMbkztvYX1j7baOrJxyLyYGWYgbnUrKRQKCtWTsO5ekIGFgtbpS8UPJNqV6j8E5XKPJ8QA7ZFqzkB0s2O__J5FrjHzc_rDo1EuRbw98ihHDzQnvuXeHapEyfhLDJct0A

        Response parameters

        Placeholder Description Example value
        <BUSINESS_TOKEN>
        The customer’s business token.
        EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn

        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.
        EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn
        <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:
        https://www.facebook.com/business/help/488291839463771
        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

        the business customer’s WABA ID (returned via session logging or API request)the business customer’s business phone number ID (returned via session logging or API request)your app ID (displayed at the top of the App Dashboard)your app secret (displayed in the App Dashboard > App settings > Basic panel)your credit line ID (displayed in Business Manager > Business Settings > Business Info or returned via API request)your system user access token (“system token”)
        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.
        AQBhlXsctMxJYbwbrpybxlo9tLPGy-QAmjBJA03jxLos43wxlBlrYozY5C33BXJULd133cOJf_5y6EkJZYMrAmW-EMj3Wdap9-NUM2nS4s8tC-ES7slBhh6QpCFM7-SzpI-iqsjqTGyxbUUW3AeaEyLkeZFIkBgcQ_SOxo9HShm20SDR5_n7AT9ZJ5dcgpqBQykNT-pQ8V7Ne9-sr6RLAWtJMF7-Zx6ABudRcWIN53tUTtquDVNuq3lrco4BlVQAv-54tR83Ae0ODN9Uet6j-BVLuetXhQCM3sz9RdgedlbxkidMbkztvYX1j7baOrJxyLyYGWYgbnUrKRQKCtWTsO5ekIGFgtbpS8UPJNqV6j8E5XKPJ8QA7ZFqzkB0s2O__J5FrjHzc_rDo1EuRbw98ihHDzQnvuXeHapEyfhLDJct0A

        Response parameters

        Placeholder Description Example value
        <BUSINESS_TOKEN>
        The customer’s business token.
        EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn

        Step 2: Subscribe to webhooks on the customer’s WABA

        Request parameters

        Placeholder Description Example value
        <BUSINESS_TOKEN>
        Required.
        The customer’s business token.
        EAAAN6tcBzAUBOwtDtTfmZCJ9n3FHpSDcDTH86ekf89XnnMZAtaitMUysPDE7LES3CXkA4MmbKCghdQeU1boHr0QZA05SShiILcoUy7ZAb2GE7hrUEpYHKLDuP2sYZCURkZCHGEvEGjScGLHzC4KDm8tq2slt4BsOQE1HHX8DzHahdT51MRDqBw0YaeZByrVFZkVAoVTxXUtuKgDDdrmJQXMnI4jqJYetsZCP1efj5ygGscZBm4OvvuCYB039ZAFlyNn
        <WABA_ID>
        Required.
        The customer’s WABA ID.
        102290129340398

        Step 3: Share your credit line with the customer

        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.
        EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD

        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.

        Authorization screen

        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

        the business customer must be using WhatsApp Business app version 2.24.17 or higher.the business customer’s phone number country code must be supportedyou must already be a Solution Partner or Tech Provideryou must know how to use Cloud APIyour webhook callback must be be able successfully accept and digest webhooksyou must be using Embedded Signup with session logging

        Limitations

        In order to remain compatible with the WhatsApp Business app, business phone numbers that are in use with both the WhatsApp Business app and Cloud API have a fixed throughput of 20 mps.If your business customer worked with a partner in the past and still shares the previous credit line, they may see an error when attempting to switch to a new partner. Follow the guide to resolve the error.

        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 131060. This is expected and can occur in the following scenarios:
        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.
        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.
        Screenshot of pre-verified phone numbers in Embedded Signup flow
        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

        Your business must be an approved Solution Partner.The app user must be a business admin on the business account that pre-verified business phone numbers are added to.A User or System User access token.The business_management permission.Business phone numbers must be valid.

        Limitations

        You are responsible for keeping track of who has claimed a pre-verified business phone number.If a pre-verified business phone number is not claimed by an end client in the Embedded Signup flow within 90 days of verification, the number will revert to an unverified status and must be verified again to have its status restored for another 90 days.Unclaimed pre-verified business phone numbers can't be re-verified until 45 days before they are scheduled to revert to an unverified status. This time is indicated by the 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

        See Getting claimed phone number IDs.

        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.
        Onboarding business customers as a Solution ProviderOnboarding business customers as a Tech Provider
        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 must have completed the steps to become a Solution Partner or Tech Provider.If your app is for messaging, it must be able to send messages, manage templates, and have a properly configured production webhook endpoint.Your app must be subscribed to the account_update webhook.Solution Partners must have a line of credit.
        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:
        Embedded Signup opt-in screen for 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

        Automatic event identification is a new feature. Your business customers won’t see or use automatic events reported via Conversions API in Meta surfaces until 2026. However, you can surface this information to your customers using your own solution before then. This allows them to gain a deeper understanding of their own customers’ needs, preferences, and ad performance.Automatic event identification is not available to business customers in the European Union, United Kingdom, or Japan.

        Requirements

        You have already implemented Embedded Signup and are able to onboard business customers who complete the flow.Your webhook server is successfully processing webhooks.

        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.
        A WhatsApp Business Account selected in the Meta Business Suite's settings panel, with the summary tab showing checkboxes for opting in.
        If a business customer who you have already onboarded wants to enable this feature, you can send them these instructions:
          Access Meta Business Suite at https://business.facebook.com.Navigate to Settings > Accounts > WhatsApp accounts and click your WhatsApp Business Account.Scroll down to Privacy and data sharing in the Summary tab.Use the “Automatically identify... “ toggles to enable or disable automatic event identification as desired.

          Versions | Developer Documentation

          Versions

          Updated: Dec 11, 2025
          The latest Embedded Signup Version is: v4
          This 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_install
          marketing_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_sharing
          whatsapp_business_app_onboarding
          marketing_messages_lite
          app_only_install
          marketing_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_install
          marketing_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_sharing
          whatsapp_business_app_onboarding
          marketing_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

          Simplified onboarding experience for businesses: You can onboard businesses to more business messaging in a single flow (see supported products).Asset selection, business information, and permissions are each consolidated onto a single page.Asset admins can share assets from other business portfolios.Phone numbers are auto-linked to Facebook Pages when onboarding to ads that click to WhatsApp via the Marketing API.Value proposition and Terms of Service are clearly presented.The Facebook Login for Business Configuration is used to define which products to add into your onboarding flow.

          Learn more

          v4 - Cloud API flow

          Supported products

          v4 supports additional business messaging products, ensuring businesses to set up and manage multiple communication channels from a single platform:
          Conversions API (WhatsApp): Track and optimize messaging interactions by selecting the messaging platform you want to monitor, enabling enhanced measurement and optimization.Click to WhatsApp Ads (CTWA): Create ads that direct users to initiate WhatsApp conversations with your business.Click to Messenger Ads (CTM): Run advertising campaigns that start conversations with users on Facebook Messenger.Click to Direct Ads (CTD): Launch Instagram ad campaigns that drive users to direct messaging conversations on Instagram Direct.

          All other supported products

          v4 continues to support existing business messaging products, allowing businesses to seamlessly manage their established communication channels.
          Cloud API: Integrate and manage WhatsApp messaging at scale, enabling businesses to send and receive messages, automate workflows, and access advanced messaging features.Marketing Messages API for WhatsApp: Utilize to manage optimized marketing messaging , providing tools for message analytics, and enhanced customer engagement.WhatsApp Business App users (aka “Coexistence”) support: Onboarding via Coexistence continues to be supported through the 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.

          Authorization screen

          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.

          Authorization screen

          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.