Sharing to Messenger for iOS and Android

When you develop with the Facebook SDK for iOS or Android version 4.29.0 or later, you can enable people to share both links and media from your apps to Messenger. These shares can be used to trigger your chat extensions via the attribution link. They will also put your chat extension in the more drawer for the sharer.

For more information, see the following sections:

For implementing sharing to Messenger for the web, see Sharing to Messenger for the Web.

Share Types

The Facebook SDK provides four attributed share types and one unattributed share types:

The following table lists all the share types supported in sharing to Messenger, along with whether a Page or App ID is required, and ways of using the template.

Share Type Page ID Required? Applications

Generic Template

Optional

  • Generic template with button
  • Generic template with default action
  • Generic template with button and default action

Media Template

Required

  • Media template image URI
  • Media template image AttachmentID
  • Media template video URL
  • Media template video attachment ID

Open Graph Music

Required

  • Open graph music

Link Share

Optional

  • Link without attribution
  • Link with attribution

Photo

Not supported

  • Photos
  • Photo from library

Linking App and Page IDs

Developers can specify a Page ID in the share flow, and when people share content from an app to messenger by way of the Sharing SDK, the content is attributed to the Page. Page administrators, in turn, can prevent false attributions by controlling which apps can use a share attribution for their Pages. To grant an app share attribution, the administrator links the app's ID with the Page ID.

To link an app ID and Page ID:

  1. Go to the Settings for the Page.
  2. Click on the Messenger Platform section.
  3. Go to the Link an App section in General Settings”.
  4. Enter the app ID and click the Link button.
  5. If this app was NOT in the Subscribed Apps table already, it will show up in the table with the “share attribution” role associated with it. If the app was already in the table, the new “share attribution” role will be added for that app.

Page administrators can also remove an app's permission to use share attribution.

To remove the “share attribution” role for a given app:

  1. In the Subscribed Apps table, click on the dropdown in the “role” column for the app.
  2. Click on the “share attribution” to deselect the role.
  3. If “share attribution” was the only role for the app, the row for the app is removed from the table. Otherwise, the row remains but the “share attribution” row is deselected.

Whitelisting Domains

If you use a URL button in the Share SDK and want to enable Messenger Extension for your URL when opened in Messenger, you have to whitelist the URL domain for the share to work correctly.

To whitelist a domain:

  1. Go to the Settings for the Page.
  2. Click on the Messenger Platform section.
  3. Go to the Link an App section in General Settings”.
  4. In the Whitelisted Domains field, enter the domain of the URL, and click Save.

For more information on whitelisting, see Messenger Extensions SDK - Required Domain Whitelisting.

IOS

Prerequisites

Before you add sharing to Messenger to your app, complete the following steps:

  • Add the Facebook SDK for iOS to your mobile development environment
  • Configure and link your Facebook app ID to your Page ID with the Messenger Platform tool.
  • Add your app ID, display name, and human-readable reason for photo access to your app's .plist file.
  • Link the FBSDKShareKit.framework to your project.

For more information, see Getting Started with the Facebook SDK for iOS

Also make sure your app calls canShow on the FBSDKMessageDialog instance to determine whether people have a compatible version of Messenger installed on their devices.

Generic Template Example Share

FBSDKShareMessengerURLActionButton *urlButton = [[FBSDKShareMessengerURLActionButton alloc] init];
urlButton.title = @"Visit Facebook";
urlButton.url = [NSURL URLWithString:@"https://www.facebook.com"];
    
FBSDKShareMessengerGenericTemplateElement *element = [[FBSDKShareMessengerGenericTemplateElement alloc] init];
element.title = @"This is a Cat Picture";
element.subtitle = @"Look at this cat, wow! Amazing.";
element.imageURL = [NSURL URLWithString:@"https://static.pexels.com/photos/126407/pexels-photo-126407.jpeg"];
element.button = urlButton;
    
FBSDKShareMessengerGenericTemplateContent *content = [[FBSDKShareMessengerGenericTemplateContent alloc] init];
content.pageID = // Your page ID, required for attribution
content.element = element;

FBSDKMessageDialog *messageDialog = [[FBSDKMessageDialog alloc] init];
messageDialog.shareContent = content;

if ([messageDialog canShow]) {
    [messageDialog show];
}

Media Template Example Share

// Share with mediaURL
FBSDKShareMessengerURLActionButton *urlButton = [[FBSDKShareMessengerURLActionButton alloc] init];
urlButton.title = @"Visit Facebook";
urlButton.url = [NSURL URLWithString:@"https://www.facebook.com"];

NSURL *mediaURL = // Must be a Facebook URL, see media template documentation
FBSDKShareMessengerMediaTemplateContent *content = [[FBSDKShareMessengerMediaTemplateContent alloc] initWithMediaURL:mediaURL];
content.pageID = // Your page ID, required
content.mediaType = FBSDKShareMessengerMediaTemplateMediaTypeImage;
content.button = urlButton;

FBSDKMessageDialog *messageDialog = [[FBSDKMessageDialog alloc] init];
messageDialog.shareContent = content;

if ([messageDialog canShow]) {
    [messageDialog show];
}

------------------------------------------------------------------

// Share with attachmentID
FBSDKShareMessengerURLActionButton *urlButton = [[FBSDKShareMessengerURLActionButton alloc] init];
urlButton.title = @"Visit Facebook";
urlButton.url = [NSURL URLWithString:@"https://www.facebook.com"];

NSString *attachmentID = // attachmentID, see media template documentation for how to upload an attachment
FBSDKShareMessengerMediaTemplateContent *content = [[FBSDKShareMessengerMediaTemplateContent alloc] initWithAttachmentID:attachmentID];
content.pageID = // Your page ID, required
content.mediaType = FBSDKShareMessengerMediaTemplateMediaTypeImage;
content.button = urlButton;

FBSDKMessageDialog *messageDialog = [[FBSDKMessageDialog alloc] init];
messageDialog.shareContent = content;

if ([messageDialog canShow]) {
    [messageDialog show];
}

Open Graph Music Example Share

FBSDKShareMessengerURLActionButton *urlButton = [[FBSDKShareMessengerURLActionButton alloc] init];
urlButton.title = @"Visit Facebook";
urlButton.url = [NSURL URLWithString:@"https://www.facebook.com"];

FBSDKShareMessengerOpenGraphMusicTemplateContent *content = [[FBSDKShareMessengerOpenGraphMusicTemplateContent alloc] init];
content.pageID = // Your page ID, required
content.url = // open graph music url, see open graph music documentation
content.button = urlButton;

FBSDKMessageDialog *messageDialog = [[FBSDKMessageDialog alloc] init];
messageDialog.shareContent = content;

if ([messageDialog canShow]) {
    [messageDialog show];
}

Android

Prerequisites

Follow the instructions in Sharing on Android, summarized below:

Also make sure your app calls MessageDialog.canshow({template}) to determine whether people have a compatible version of Messenger installed on their devices.

Generic Template Example Share

ShareMessengerURLActionButton actionButton =
    new ShareMessengerURLActionButton.Builder()
           .setTitle("Visit Facebook")
           .setUrl(Uri.parse("https://www.facebook.com"))
           .build();
ShareMessengerGenericTemplateElement genericTemplateElement =
    new ShareMessengerGenericTemplateElement.Builder()
           .setTitle("Visit Facebook")
           .setSubtitle("Visit Messenger")
           .setImageUrl(Uri.parse("heeps://Your/Image/Url"))
           .setButton(actionButton)
           .build();
ShareMessengerGenericTemplateContent genericTemplateContent = 
    new ShareMessengerGenericTemplateContent.Builder()
           .setPageId("Your Page Id") // Your page ID, required
           .setGenericTemplateElement(genericTemplateElement)
           .build();  
                 
if (MessageDialog.canShow(genericTemplateContent)) {
    MessageDialog.show(activityOrFragment, genericTemplateContent);
}

Media Template Share

// Share with mediaURL
ShareMessengerMediaTemplateContent mediaTemplateContent =
    new ShareMessengerMediaTemplateContent.Builder()
            .setPageId("Your page ID") // Your page ID, required
            .setMediaType(MediaType.IMAGE)
            .setMediaUrl(Uri.parse("https://Facebook/Media/URL")) // Must be a Facebook URL, see media template documentation
            .setButton(actionButton)
            .build();
if (MessageDialog.canShow(mediaTemplateContent)) {
    MessageDialog.show(activityOrFragment, mediaTemplateContent);
}

// Share with attachmentID
ShareMessengerMediaTemplateContent mediaTemplateContent =
    new ShareMessengerMediaTemplateContent.Builder()
            .setPageId("Your page ID") // Your page ID, required
            .setMediaType(MediaType.IMAGE)
            .setAttachmentId("Attachment Id") // AttachmentID, see media template documentation for how to upload an attachment
            .setButton(actionButton)
            .build();
if (MessageDialog.canShow(mediaTemplateContent)) {
    MessageDialog.show(activityOrFragment, mediaTemplateContent);
}

Open Graph Music Example Share

ShareMessengerOpenGraphMusicTemplateContent musicTemplateContent =
    new ShareMessengerOpenGraphMusicTemplateContent.Builder()
                .setPageId("Your page ID") // Your page ID, required
                .setUrl(Uri.parse("https://Open/Graph/Music/URL")) // Open graph music url, see open graph music documentation
                .setButton(actionButton)
                .build();

if (MessageDialog.canShow(musicTemplateContent)) {
    MessageDialog.show(activityOrFragment, musicTemplateContent);
}