Graph API Version

Sharing from the Messenger Webview

Sharing is an important part of the Messenger experience, so we made it easy to enable the people your bot interacts with to share the pages you display in the Messenger webview. This creates a great opportunity for your bot to gain exposure.

Contents

Default Sharing

Webviews, by default, now allow the user to share pages from your bot into conversations in Messenger.

When the link is shared, the resulting bubble will include an attribution that will allow the recipient to try your bot.



To control the contents of the message bubble that results when a user decides to share your page in this way, we suggest setting Open Graph meta tags for the page.

To more closely control the bubble, or to create a custom call-to-action for the recipient to tap, try Customized Sharing in Messenger Extensions, discussed below.

Disabling Default Sharing

There may be cases where you do not wish to allow the user to share from the webview (for instance when it is showing sensitive information or a web app that only works for bot users).

For this reason, there is now a webview_share_button attribute for both menu items and URL buttons. Set it to hide to disable sharing functionality in the webview. You may wish to use this if the webview is showing sensitive information.

Note that this attribute only hides the visible share button in the webview chrome; shares your bot initiates using beginShareFlow() will still work.

Customized Sharing

Users can already share from the webview if they like a piece of content from your bot.

But you may wish to customize the experience more. For instance, you might want to control the formatting of the resulting bubble and give the recipient a specific call to action (e.g. "Buy", "Play). Or you may wish to direct the recipient into some specific flow (e.g. filling out an RSVP or taking a survey) that's hosted at a different URL than the one the sender is seeing.

Messages sent from the share button can also be customized in a similar fashion via the share_contents attribute.

Policy Reminder Messages shared via these APIs are subject to Facebook Platform Policy. Bots may not incentivize sharing or lead users to share in a deceptive manner.

Using beginShareFlow()

beginShareFlow() lets you begin a share. Call it from a "Share" button on your page, passing in the message you want to share.

The user will then be presented with a dialog where they can preview the message contents, enter a message, and choose which friends or groups to send it to.

In addition to the contents you specify, the message will automatically include an attribution link for the recipient to try your bot.

Example Request


For a complete reference of method parameters, see the beginShareFlow() Reference.

let message = {
  "attachment":{
    "type":"template",
    "payload":{
      "template_type":"generic",
      "elements": [{
        "title":"I took Peter's 'Which Hat Are You?' Quiz",
        "image_url": "https://bot.peters-hats.com/img/hats/fez.jpg",
        "subtitle": "My result: Fez",
        "default_action":{
          "type":"web_url",
          "url": "https://bot.peters-hats.com/view_quiz_results.php?user=24601"
        },
        "buttons":[{
          "type":"web_url",
          "url":"https://bot.peters-hats.com/hatquiz.php?referer=24601",
          "title":"Take the Quiz"
        }]
      }]
    }
  }
};

MessengerExtensions.beginShareFlow(function(share_response) {
  // User dismissed without error, but did they share the message?
  if(share_response.is_sent){
    // The user actually did share. 
    // Perhaps close the window w/ requestCloseBrowser().
  }
}, 
function(errorCode, errorMessage) {      
// An error occurred in the process

},
message,
"broadcast");

Message Contents


Note that the object specifying the message to be shared is identical to that of the send API. However several additional caveats apply:

The message may only be of the following types:

  • A generic template. The format is identical to that specified in the Send API docs. However, only up to one button is allowed, and it must be a URL button.

Share Modes


The mode parameter allows two choices:

broadcast mode: Prompts the person to share with other friends and conversations. Recommended for inside the bot itself, as well as for users encountering content from your bot via shared links.

current_thread mode: Prompts the person to share directly to the conversation where the webview was opened. Recommended for use inside Chat Extensions.


Response

The response object passed to the success callback tells you the result of the share. If the user finished their share, you may wish to proceed to another stage or close the webview.

{
  "is_sent": true  
}

Best Practices

If your bot shares pieces of content or links that are not particularly tailored for Messenger, it's best to leave the default sharing button on.

If you use customized sharing features in the webview, it's best to turn the default webview share button off, as the resulting bubble may be less effective than the one you would generate.

In accordance with Facebook Platform Policy, don't incentivize the user to share or block functionality unnecessarily.

In the webview, don't open the share flow without user action.