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.

Here's a full example of calling it:

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");

The function takes the following parameters:

Parameters

Parameter Type Description

success

Function

This function will be called when the user dismisses the share flow (regardless of whether a share actually occurred).

error

Function

This function will be called only when there was an error invoking the share flow or sharing the message.

message

Object

This specifies the message bubble that will be shared.

mode

String

The mode to share in. Musrt be either broadcast or current_thread.

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  
}