Adding Messenger Extensions

Messenger Extensions allow you to do much more than you could in a normal web app. With them, you can get information on the user, accept payments, make your bot viral with sharing, and deeply integrate with Messenger's UI.

Getting Started

1. Whitelist your Domain

To use Messenger Extensions in your bot, you must first whitelist the domain the page is served from. This is 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 library

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:

<script>
(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'));
</script>      

3. Respond to the SDK Loaded 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.

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

Messenger Extensions on Web (new in v2.1)

Messenger Extensions are now supported on both mobile and desktop. However, you may have to consider the following to make it work properly:

Allow loading of your pages in iframe on Messenger and Facebook domains

We use iframe to present your pages on Messenger web and Facebook chat tabs. You have to set up proper X-Frame-Options HTTP response header to allow your pages within an iframe. E.g.

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

Additionally, you can use the window.name property to check location of the iframe on client side.

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

Other caveats

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