Messenger Extensions SDK

Updated: Jun 17, 2026

The Messenger Extensions SDK adds Messenger-specific features to any website or web app that opens 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 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.

Close the webview

The requestCloseBrowser() method allows you to programmatically close the webview and return the user to the conversation in Messenger.

MessengerExtensions.requestCloseBrowser(success, error)

Parameter	Type	Description
`success`	Function	Success callback function.
`error`	Function	Error callback function.

MessengerExtensions.requestCloseBrowser(function success() {
  // webview closed
}, function error(err) {
  // an error occurred
});

Install the SDK

1. Allowlist your domain

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

You can add a domain to the allowlist programmatically using the following API:

curl -X POST -H "Content-Type: application/json" -d '{
  "whitelisted_domains":[
    "https://petersfancyapparel.com"
  ]
}' "https://graph.facebook.com/v25.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 that loads 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

Messenger calls window.extAsyncInit() when the Messenger Extensions JS SDK finishes 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 Messenger web triggers the iframe, Messenger sets window.name to "messenger_ref". Otherwise, when the iframe loads on Facebook chat tabs, Messenger sets window.name to "facebook_ref".

Unsupported features

The following settings or features are not supported on Messenger web clients. These settings and features 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 allowlisted 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 you serve the page over https without any non-standard port.