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, accept payments, share content to conversations in Messenger, and deeply integrate with the Messenger UI.

Contents

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.

FunctionDescription

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.

beginShareFlow()

Share content from the webview to conversations in Messenger.

askPermission()

Request permission to do things like retrieve a person's profile information.

getGrantedPermissions()

Check currently granted permissions.

PaymentRequest

Base object for initiating payments in the webview.

getSupportedFeatures

Check what features are supported in the webview on the current device, such as payments and 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 domain the page is served from for security reasons. 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/v2.6/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.com/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

As of v2.1 of the Messenger Platform, 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.

Allow iframe Loading on Messenger and Facebook Domains

The Messenger and Facebook web clients open your pages in an iframe. To allow this, ensure your web server returns the X-Frame-Options header in the HTTP response: E.g.

X-Frame-Options: ALLOW-FROM https://www.messenger.com/
X-Frame-Options: ALLOW-FROM https://www.facebook.com/

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.

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.