Adding the Messenger Extensions SDK

The Messenger Extensions SDK brings valuable, Messenger-specific features to any website or web app that is opened in the Messenger webview. With the SDK, you can retrieve information about the person that opened the webview, share content to conversations in Messenger, and deeply integrate with the Messenger UI.

Available Features

The following features are available in the Messenger webview when you include the Messenger Extensions SDK. Please note that actual availability of features may vary based on the version of Messenger and device.

Function	Description
getContext()	Retrieve conversation context such as the PSID of the person that opened the webview.
requestCloseBrowser()	Close the webview and return to the Messenger conversation.
askPermission()	Request permission to do things like retrieve a person's profile information.
getGrantedPermissions()	Check currently granted permissions.
getSupportedFeatures	Check what features are supported in the webview on the current device, such as sharing.

For complete details on using these features, see the Messenger Extensions SDK reference.

Installing the SDK

1. Whitelist your domain

To use Messenger Extensions in your bot, you must first whitelist the domains the page is served from; for security reasons, all domains on your webpage have to be added to the whitelisted domains. Refer to the reference doc on whitelisting for more details.

You can easily add a domain to the whitelist programatically using the following API:

 
curl -X POST -H "Content-Type: application/json" -d '{
  "whitelisted_domains":[
    "https://petersfancyapparel.com"
  ]
}' "https://graph.facebook.com/v21.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

On success, the Messenger Profile API will respond:

{"result":"success"}

2. Include the Messenger Extensions JS SDK

Add the Messenger Extensions Javascript SDK to the page being loaded in the webview with the code below. You should insert it directly after the opening body tag on each page you want to load it:

(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 = "//connect.facebook.net/en_US/messenger.Extensions.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'Messenger'));

3. Wait for the SDK load event

window.extAsyncInit() will be called when the Messenger Extensions JS SDK is done loading. You can use this as a trigger to call other functions available in the SDK.

window.extAsyncInit = function() {
  // the Messenger Extensions JS SDK is done loading 
};

Using the SDK in the Messenger Web Client

The Messenger Extensions SDK is supported for use on both mobile and desktop Messenger clients. However, you may have to consider the following to make it work properly.

You can also use the window.name property to check the location of the iframe from your client-side code.

When the iframe is triggered on Messenger web, we set window.name to be "messenger_ref". Otherwise, when loading on Facebook chat tabs, window.name will be "facebook_ref".

Unsupported Features

The following settings or features are not supported on Messenger web clients. They still function properly on Messenger mobile clients.

webview_height_ratio
webview_share_button
Navigation back buttons
Dialog title
Closing the webview via URL redirect

Troubleshooting

If you're not able to call the Messenger Extensions SDK from your page, consider the following:

When you are opening the webview from the persistent menu or a button, ensure that the messenger_extensions parameter is set to true. If a user has opened the webview via a shared message, it is not required that they have talked to your bot for Messenger Extensions to work.
Check that you have whitelisted the domain the page is hosted on.
Check that the JS SDK is included on every page that uses extensions.
Make sure you are not attempting to call any functions before the SDK has finished loading. Use window.extAsyncInit described here to tell when loading is done.
Make sure that the page is being served over https and does not include any non-standard port.