Embed the Signup Flow

The Facebook JavaScript SDK and Facebook Login allow you to embed the signup flow into your website or client portal.

Step 1: Load the Facebook JavaScript SDK

The fbAsyncInit function must be attached to the window object before the line of code loading the JavaScript SDK as the SDK calls this function to set up the Facebook Login information.

This setup uses the following parameters:

• appId — The Meta app ID
• cookie — Enables cookies to allow the server to access this session
• xfbml— Parses social plugins on the page
• version — The Graph API version to use

Example

<script>
  window.fbAsyncInit = function () {
    // JavaScript SDK configuration and setup
    FB.init({
      appId:    'facebook-app-id', // Meta App ID
      cookie:   true, // enable cookies
      xfbml:    true, // parse social plugins on this page
      version:  'v19.0' //Graph API version
    });
  };
</script>

Step 2: Create Facebook Login for Business Configuration

• Load your app in the App Dashboard on https://developers.facebook.com/
• Add the Facebook Login for Business product
• Follow best practices on how to set up Client OAuth settings, specifically settings like Valid OAuth Redirect URIs and Allowed Domains for the JavaScript SDK

Step 3: Set up Facebook Login

Facebook Login allows you to place a button on your website or portal to initiate a connection to Facebook. Businesses can use this login flow to associate their Facebook profiles with their business presence (i.e., Business Manager) in order to streamline onboarding.

The Facebook Login button should be implemented in a location of your choice (platform portal, landing page, etc.) using the instructions below to trigger the Embedded Signup oAuth flow.

After loading the JavaScript SDK and initializing it with the proper information, set up the FB.login() function to trigger the Embedded Signup flow.

Make sure the following are included:

• The response callback function
• The config_id parameter
• The extras object with:
  • The setup parameter for any prefilled form data

Example

<script>
  window.fbAsyncInit = function () {
    // JavaScript SDK configuration and setup
    FB.init({
      appId:    'your-facebook-app-id', // Facebook App ID
      cookie:   true, // enable cookies
      xfbml:    true, // parse social plugins on this page
      version:  'v19.0' //Graph API version
    });
  };

  // Load the JavaScript SDK asynchronously
  (function (d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s); js.id = id;
    js.src = "https://connect.facebook.net/en_US/sdk.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'facebook-jssdk'));

  // Facebook Login with JavaScript SDK
  function launchWhatsAppSignup() {
    // Conversion tracking code
    fbq && fbq('trackCustom', 'WhatsAppOnboardingStart', {appId: 'your-facebook-app-id', feature: 'whatsapp_embedded_signup'});
    
    // Launch Facebook login
    FB.login(function (response) {
      if (response.authResponse) {
        const code = response.authResponse.code;
        // The returned code must be transmitted to your backend, 
  // which will perform a server-to-server call from there to our servers for an access token
      } else {
        console.log('User cancelled login or did not fully authorize.');
      }
    }, {
      config_id: '<CONFIG_ID>', // configuration ID goes here
      response_type: 'code',    // must be set to 'code' for System User access token
      override_default_response_type: true, // when true, any response types passed in the "response_type" will take precedence over the default types
      extras: {
        setup: {
          ... // Prefilled data can go here
        }
      }
    });
  }
</script>

Step 4 (Strongly Recommended): Implement Pre Filled Data and Pre-Verified Phone Numbers Support

Our data shows that businesses which implement support for the Pre Filled Data and Pre-Verified Phone Numbers result in higher onboarding rates.

Step 5: Create a Login Button

Create a button or link on your website to launch the Embedded Signup flow. Use the onClick function to call the launchWhatsAppSignup() function set up in Step 3.

Example

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

Step 6 (Optional): Legacy Version Support

Current version of WhatsApp Embedded Signup is version 2

To display version 1 of Embedded Signup to your customers you can do it by specifying the following login configuration. Note that WhatsApp Embedded Signup version 1 requires the following permissions with advanced access:

• business_management
• whatsapp_business_management
• whatsapp_business_messaging

{
  "scope": "business_management, whatsapp_business_management, whatsapp_business_messaging",
  "extras": {
    "feature": "whatsapp_embedded_signup",
    // Display original flow to user
    "version": 1,
    "setup": {
      ... // Prefilled data 
    }
  }
});

Step 7 (Optional): Session Logging

You can now get detailed information about a user as they go through the Embedded Signup user journey.

This detailed information is either one of:

• The step where the user canceled the flow if the user canceled the Embedded Signup flow
• The user's phone and WABA IDs if the user successfully completed the Embedded Signup flow

{
  "config_id": "<CONFIG_ID>", // configuration ID goes here
  "response_type": "code",    // must be set to 'code' for System User access token
  "override_default_response_type": true, // when true, any response types passed in the "response_type" will take precedence over the default types
  "extras": {
    "sessionInfoVersion": 2,  //  Receive Session Logging Info
  }
}

In addition to specifying the parameters outlined above, add this JavaScript code on your platform

const sessionInfoListener = (event) => {
  if (event.origin !== "https://www.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;
      }
      // if user cancels the Embedded Signup flow
      else {
       const{current_step} = data.data;
      }
    }
  } catch {
    // Don’t parse info that’s not a JSON
    console.log('Non JSON Response', event.data);
  }
};

window.addEventListener('message', sessionInfoListener);  

Returned Payload

If the user completes the flow successfully, the returned payload will have the sessionInfo object contain the following information:

{
  data: {
    phone_number_id: "<PHONE-ID>",
    waba_id: "<WABA-ID>",
  },
  type: "WA_EMBEDDED_SIGNUP",
  event: "FINISH",
  version: 2
}

If the user cancels the flow, the returned payload will have the sessionInfo object contain the following information:

{
  data: {
    current_step: "<Current Step ID>",
  },
  type: "WA_EMBEDDED_SIGNUP",
  event: "CANCEL",
  version: 2
}

You can get more details about when the user canceled the flow with the value of currentStep:

Step 8 (Optional): Bypass Phone Number Selection

If you are showing your users the new Embedded Signup flow but do not want them to have to enter or choose a business phone number, you can include the featureType object property set to only_waba_sharing. This removes the phone number entry/selection portion of the new flow.

Later, you can use WhatsApp Manager to assign phone numbers to onboarded end clients, or use our phone number registration and business profile endpoints to add numbers and business profiles programmatically (or build a UI for your onboarded clients that calls these endpoints).

{
  "config_id": "<CONFIG_ID>", // configuration ID goes here
  "response_type": "code",    // must be set to 'code' for System User access token
  "override_default_response_type": true, // when true, any response types passed in the "response_type" will take precedence over the default types
  "extras": {
    "featureType": "only_waba_sharing" // Bypass phone number selection
  }
}

If using session logging, data.event will be set to FINISH_ONLY_WABA when the user completes the flow.

After Business Completes Signup Flow

When a business finishes the Embedded Signup flow, the flow returns an authResponse object with a code property:

{
  "authResponse": {
    "userID": null,
    "expiresIn": null,
    "code": "<CODE_TO_BE_EXCHANGED>"
  },
  "status": "connected"
}

Exchange this code for a business integration system user access token by performing a server-to-server call to our GET /oauth/access_token endpoint.

GET https://graph.facebook.com/v17.0/oauth/access_token?
  client_id=<APP_ID>
  &client_secret=<APP_SECRET>
  &code=<CODE>

Required parameters:

• client_id: Your app's IDs
• client_secret: Your unique app secret, shown on the App Dashboard.
• code: The parameter received from the Login Dialog redirect above.