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:  'v21.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:  'v21.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": {
    "feature": "whatsapp_embedded_signup",
    "sessionInfoVersion": 3  //  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 == null) {
    return;
  }
  
  // Make sure the data is coming from facebook.com
  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 reports an error during the Embedded Signup flow
      else if (data.event === 'ERROR') {
      	const {error_message} = data.data;
        console.error("error ", error_message);
      }
      // if user cancels the Embedded Signup flow
      else {
       const{current_step} = data.data;
       console.warn("Cancel at ", current_step);
      }
    }
  } 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: 3
}

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: 3
}

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.

Use the business integration system user access token obtained above to complete the steps below for integrating with the WhatsApp Business Account(WABA) that was shared with you:

Step 1: Get WABA ID

There are a couple of ways you can obtain the WABA ID that was shared with you during the Embedded Signup flow:

Option 1: Via Session Logging

If you have set up the session logging option for your Embedded Signup script, a payload containing the WABA ID and the Phone number ID will be sent to your callback. Please refer to this section

Option 2: Via Graph APIs

Please refer to these available APIs

GET "https://graph.facebook.com/<API_VERSION>/debug_token
?input_token=<BUINESS_INTEGRATION_SYSTEM_TOKEN>"

Step 2: Get Phone Number ID

There are a couple of ways you can obtain the Phone number ID connected to the WABA that was shared with you during the Embedded Signup flow:

Option 1: Via Session Logging

If you have set up the session logging option for your Embedded Signup script, a payload containing the WABA ID and the Phone number ID will be sent to your callback. Please refer to this section

Option 2: Via Graph API

You can use the phone_numbers endpoint to retrieve phone number details including the phone number id. Please use the WABA ID obtained in the previous step for the call.

GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-id}/phone_numbers
?access_token=<BUINESS_INTEGRATION_SYSTEM_TOKEN>"

Step 3: Register Phone Number

Use the Phone number ID obtained in the previous step to register the phone number

Note: Please use the business integration system user access token above

Step 4: Subscribing For Webhook Notifications

If you wish to receive webhooks for the WABA that was shared with you, subscribe to the WABA via the subsribed_apps endpoint. Ensure that your app has subscribed to the needed webhooks at an app level as called out in the doc.

POST "https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps"

Note: Please use the business integration system user access token above

Step 5: Sending Message To A Customer Initiated Thread

For sending a business initiated message you need to have a payment method in place for the WABA. However, if you would like to test message sends you can act as an end user and send a message to the phone number that was connected to the WABA, which will open up the window for you to send a message back via the API. Note: This flow can be used to create the video for the app review for whatsapp_business_messaging

• Send a message from a customer WhatsApp number (for e.g Your personal WhatsApp phone number or a test phone number you own) to the WhatsApp number that is attached to the shared WABA Once you have sent a message, you can reply to the message by using the send message API.

Note: Please use the business integration system user access token above

Step 6: Attaching System User To WABA

Adding your System User to the shared WhatsApp Business Accounts allows you to programmatically manage the accounts. Please refer to this doc for steps.

Step 7: Attaching Payment Method To WABA

• If you are working as an independent Tech Provider and are onboarding clients yourself, you should ask your client to add a credit card as a payment to the WABA. This can be done from the Business Portfolio UI and selecting the WABA and going to the Settings tab:

• However, if you are a Tech Provider working with a Solution Partner via Multi-partner solutions to manage the customer’s WABA then the Solution Partner's line of credit needs to be set as the payment method for the shared WABA. This can be done by the Solution Partner using details mentioned in this doc

That completes all the needed steps once a business onboards.