The Facebook JavaScript SDK and Facebook Login allow you to embed the signup flow into your website or client portal.
See Basic Setup for instructions on loading the basic version of the Facebook JavaScript SDK with the options set to their most common defaults.
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 IDcookie
— Enables cookies to allow the server to access this sessionxfbml
— Parses social plugins on the pageversion
— The Graph API version to use
<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>
At the present Facebook Login for Business is in the process of being rolled out for all of our customers. Please refer to the previous version of documentation describing how to set up Facebook Login using user access tokens as an alternative approach
whatsapp_business_management
and whatsapp_business_messaging
permissions
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:
response
callback functionconfig_id
parameterextras
object with:
setup
parameter for any prefilled form data
<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>
Our data shows that businesses which implement support for the Pre Filled Data and Pre-Verified Phone Numbers result in higher onboarding rates.
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.
<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>
Current version of WhatsApp Embedded Signup is version 2
WhatsApp Embedded Signup version 1 is currently in maintenance state and will be deprecated on October 31st, 2023.
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:
{ "scope": "business_management, whatsapp_business_management, whatsapp_business_messaging", "extras": { "feature": "whatsapp_embedded_signup", // Display original flow to user "version": 1, "setup": { ... // Prefilled data } } });
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:
{ "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);
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
:
Current Step ID | Description |
---|---|
| When a user creates or selects a Meta Business Account to manage WhatsApp Messages |
| When a user creates or selects a WhatsApp Business Account. If they select an existing WhatsApp Business Accountm they can select an existing WhatsApp Phone Profile or create a new one |
| When the user creates a WhatsApp Phone Profile |
| When the user enters their phone number |
| When the user verifies their phone number |
| When the user verifies the permissions |
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.
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.
Never include your app secret in client-side code or in binaries that could be decompiled. It is extremely important that it remains completely secret as it is the core of the security of your app and all the people using it.
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 IDsclient_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:
There are a couple of ways you can obtain the WABA ID that was shared with you during the Embedded Signup flow:
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
Please refer to these available APIs
GET "https://graph.facebook.com/<API_VERSION>/debug_token ?input_token=<BUINESS_INTEGRATION_SYSTEM_TOKEN>"
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:
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
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>"
Use the Phone number ID obtained in the previous step to register the phone number
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"
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
Adding your System User to the shared WhatsApp Business Accounts allows you to programmatically manage the accounts. Please refer to this doc for steps.
That completes all the needed steps once a business onboards.