Messenger Platform

 
 
 

Webview

The Messenger Platform allows you to open a standard webview, where you can load webpages inside Messenger. This lets you offer experiences and features that might be difficult to offer with message bubbles, such as picking products to buy, seats to book, or dates to reserve.

Contents

Displaying the Webview

You can open the webview with any of the following:

In each of these instances, you can specify how the webview should look and behave.

If your bot uses the Messenger Extensions described in this section, remember to set the messenger_extensions parameter to true in the menu item or button you are invoking it from!

Required Domain Whitelisting

To display a webpage in the Messenger webview you must whitelist the domain, including sub-domain, in the whitelisted_domains property of your bot's Messenger Profile. This ensures that only trusted domains are opened by your Messenger bot.

For more information on whitelisting domains, see the whitelisted_domains reference.

Setting Webview Height

You can specify the height of the webview when it opens in messenger by setting the webview_height_ratio property when configuring any of the entry points above. The following sizes are supported:

  • compact
  • tall
  • full

Setting Webview Title

As with any webpage, the <title> tag sets the text displayed in the title bar for the webview.

<html>
  <head>
    <title>My Awesome Webview</title>
  </head>
   ...
</html>

Closing the Webview

It is a good idea to close the webview after a transaction is complete, especially if actions the user took will result in a message in the thread. This can be done with the Messenger Extensions SDK or by using a redirect URL.

Closing with Messenger Extensions SDK

To close the webview using the Messenger Extensions SDK, call MessengerExtensions.requestCloseBrowser(). You can also optionally implement success and error callbacks functions.

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

Closing with Redirect

You can also close the webview by redirecting the user to a URL with the following format:

https://www.messenger.com/closeWindow/?image_url=<IMAGE_URL>&display_text=<DISPLAY_TEXT>

The values set for the display_text and image_url parameters will be displayed briefly until the window closes. Note that this method will only close if you redirect from your URL/Page. Directly opening the URL will not close the browser.

This only works on Android. On iOS, the text and image will be displayed, but the browser will not close automatically.

Messenger Extensions SDK

To give you the ability to tightly integrate experiences in the webview with the Messenger experience, we also have made the Messenger Extensions JS SDK available, which makes added functionality accessible in the webview, such as payments and information about the thread context.

For more information, see Adding the Messenger Extensions SDK.

Best Practices

Use it for longer interactions (more than three steps) where people might want to edit their input or otherwise proceed in a non-linear fashion.

Use it for content that's especially visual.

Use it for user preferences, or to allow on-demand changes to previous selections.

Use it in combination with more conversational interactions.

Configure the height of your webview to match its content — and preserve the context of the thread beneath.

Keep webview interactions brief: it's still a bot, and your user's attention is still divided.

Take advantage of Messenger's webview extensions to bring the thread's context into the webview.

Don't feel limited to collecting all form information at once. You can capture it piece by piece conversationally, then use a form in the webview for later edits.

Don't build an app inside a thread instead of a bot. Mix conversational and webview interactions, and keep any given interaction brief. Combine thread and webview interactions for a "Messenger-native" experience.

Example Uses

  • A ticket-search bot can display an interactive stadium seat map for choosing a seat.
  • A travel bot can provide travel preferences—aisle vs. window, inn vs. hotel, dietary needs—accessible from the persistent menu.
  • A dental-appointment bot can display an interactive calendar for choosing an appointment slot.
  • A news bot can provide a multi-select list of topics to subscribe to.
  • A commerce or brand bot can offer personal preferences to customize offers and free gifts. (See demo below.)

Recommended Design Flow

  1. People access your webview experience one of two ways: via a button if it's part of a larger conversational flow, or a menu item for ongoing access (e.g., preferences)—or both.
  2. Your experience appears as a layer over the thread—full screen, at 75% height, or at 50% height, depending on your content and use case.
  3. You may want to send content to the thread during or after the webview interaction.
  4. When they're done, people can close the webview and return to the thread—or you can close it yourself in response to actions they take (e.g., a Save button).