Meta is updating Embedded Signup (ESU) onto a single flow built around Facebook Login for Business. Today in Embedded Signup v2 or v3, your code defines the products and permissions your customers grant when they sign up. In v4, you select those products once when you create a configuration in the Meta App Dashboard, and Meta applies the permissions each product needs.

Notice: On October 15, 2026, Meta is retiring WhatsApp Embedded Signup v2 and v3. You’ll need to make sure you have an Embedded Signup v4 configuration before October 15 or you won’t be able to onboard new customers.

Your existing customers and senders will keep working. The change applies to new onboarding, so without a v4 configuration your signup flow won’t be able to onboard new customers until you update. The changes you’ll need to make will take a couple hours up to one week to complete, including tests, depending on your configuration.

This guide details the changes you need to make to update to Embedded Signup v4. We have divided this into two parts, the first part is required for all customers and the second part is additional action required for customers using Twilio SMS-capable numbers in their workflows.

Part one - Everyone: Create a new configuration in the Meta App Dashboard and update your code to use the new configuration ID

The configuration is what lets your customers sign in with their Facebook account, select or create their Meta Business Portfolio and WABA, and then share the assets with your app and business. You can have two configurations at the same time. Your current configuration will keep working until October 15, 2026, so you can create the new one alongside it and move a few customers over first to test it out.

Follow these steps to create the new configuration ID and update your code:

On the App Dashboard home page, find the Facebook Login for Business card and click Set Up.
Select Configurations, and click Create Configuration.
Enter a name for the configuration. The name won't be visible to your customers.
Click Next.
For Login variation, choose WhatsApp Embedded Signup.
Click Next.
For Products, select WhatsApp Cloud API and Marketing Messages API for WhatsApp.
Note: Selecting the Marketing Messages (MM) API lets customers accept the MM API Terms of Service during Embedded Signup.
Click Next.
For Choose access token, select System-user access token and leave the default token expiration as 60 days. The access token section refers to your Meta Graph API access token. Since you're working with Twilio and won't call Meta's Graph API directly, this setting is not relevant for you.
Click Next.
For Assets, make sure WhatsApp accounts is selected.
Click Next.
For Permissions, make sure the whatsapp_business_management and whatsapp_business_messaging permission is selected. Don't include any other permissions.
Click Create.
Copy and save the resulting Configuration ID into your Embedded Signup launch function, and remove sessionInfoVersion 3 from the extras object.

// Handle WhatsApp Embedded Signup
function launchEmbeddedSignup() {
  // Launch Facebook login
  FB.login(
    function (response) {
      // Since you are using Twilio's APIs, you do not need to do anything with the response here.
    },
    {
      config_id: "REPLACE_WITH_YOUR_NEW_CONFIG_ID",
      auth_type: "rerequest", // Avoids 'user is already logged' in errors if users click the button again before refreshing the page
      response_type: "code",
      override_default_response_type: true,
      extras: {
        setup: {
          solutionID: "YOUR_SOLUTION_ID" // This is the Partner Solution ID
        }
      }
    }
  );
}

Part two - Tech Providers using Twilio SMS-capable phone numbers in their flow: Update how your customers verify Twilio SMS-capable numbers

The only_waba_sharing setting is removed in ESU v4. This setting was used to skip the phone-number screens in ESU to avoid your customer needing to input an OTP code when using a Twilio SMS-capable number.

If you use Twilio SMS-capable numbers, your end user will now always need to provide an OTP in the ESU flow (after the first sender is onboarded, you can still skip ESU and use the Senders API directly to rely on Twilio's automatic OTP validation). The OTP for ESU will be delivered to your customer’s Twilio message logs in console, the same way Twilio Voice numbers work today, so you’ll need to update the way you then forward the OTP on to your customers by configuring an incoming message webhook on the Phone Number (not on the WhatsApp Sender). Alternatively, you can also use Event Streams to listen for incoming messages across all numbers and senders in your account and send them to a webhook or other sink. Follow the steps in our Getting Started documentation for Event Streams and subscribe to the Inbound Message Event.

To configure an incoming message webhook:

In the new Twilio console:
1. Go to Numbers & senders and select the number you want to update.
2. Select the Configuration details tab.
3. Select Messaging, then click Edit configuration details.
4. On the Edit messaging configuration dialog, select the Webhook, TwiML Bin, Function, Studio Flow, Proxy Service option.
5. Under How do you want to set up your primary method?, select Webhook.
6. Paste your webhook into the input box.
In the Legacy Twilio console:
1. Open the Active Numbers page.
2. Click your Twilio phone number.
3. In the Messaging Configuration section, in the Configure with row, select Webhook, TwiML Bin, Function, Studio Flow, Proxy Service.
4. In the A message comes in row, select Webhook and set the URL to the webhook you want to use.
By API:
1. Use the update IncomingPhoneNumber endpoint to update the incoming webhook URL using the smsUrl parameter.
  Example:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json" \ 
--data-urlencode "SmsUrl=https://www.your-new-message-url.com/example" \ 
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

NOTE: Embedded Signup is only required for the first sender per WABA. For subsequent Twilio SMS-capable senders, we recommend using the Senders API, because Twilio verifies those numbers automatically for you and you won’t need to worry about sending the OTP on to your customer. The manual OTP code input is only required in the ESU flow.

Optional: Update your embeddedSignupInfoListener to remove logic related to only_waba_sharing

Update your embeddedSignupInfoListener by removing the FINISH_ONLY_WABA field. While not required, you can safely remove it from your embedded signup listener as an optional step to keep your code clean.

const embeddedSignupInfoListener = (event) => {
  if (!event.origin.endsWith('facebook.com')) return;
  try {
        const data = JSON.parse(event.data);
        if (data.type === 'WA_EMBEDDED_SIGNUP') {
          
          // if user finishes the Embedded Signup flow
          if (data.event === 'FINISH') {
            const {phone_number_id, waba_id} = data.data;
            console.log('Phone number ID ', phone_number_id, ' WhatsApp business account ID ', waba_id);
      
          // if user cancels the Embedded Signup flow
          } else if (data.event === 'CANCEL') {
            const {current_step} = data.data;
            console.warn('Cancel at ', current_step);

          // if user reports an error during the Embedded Signup flow
          } else if (data.event === 'ERROR') {
            const {error_message} = data.data;
            console.error('error ', error_message);
          }
        }
      } catch {
        console.log('Non JSON Responses', event.data);
      }
};

Additional Links