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:

• Share Types
• Linking App and Page IDs
• Whitelisting Domains
• iOS
• Android

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:

• Generic Template
• Media Template
• Link Share (The same as the existing link share but with a pageID for attribution)
• Photo (Unattributed)

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.

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. View the Page.
2. Navigate to Settings > Advanced Messaging.
3. Add the domain to the Whitelisted Domains field.

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.

Limitations

The quote property is not supported.

Link Share Example

Swift

guard let url = URL(string: "https://newsroom.fb.com/") else {
    preconditionFailure("URL is invalid")
}

let content = ShareLinkContent()
content.contentURL = url

let dialog = MessageDialog(content: content, delegate: self)

do {
    try dialog.validate()
} catch {
    print(error)
}

dialog.show()

Objective-C

FBSDKShareLinkContent *content = [[FBSDKShareLinkContent alloc] init];
content.contentURL = [NSURL URLWithString:@"https://newsroom.fb.com/"];

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

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

Photo Share Example

Swift

// Assumes your assets contain an image named "puppy"
guard let image = UIImage(named: "puppy") else {
    return
}

let photo = SharePhoto(image: image, userGenerated: true)
let content = SharePhotoContent()
        content.photos = [photo]

let dialog = MessageDialog(content: content, delegate: self)

// Recommended to validate before trying to display the dialog
do {
    try dialog.validate()
} catch {
    print(error)
}

dialog.show()

Objective-C

FBSDKSharePhotoContent *content = [[FBSDKSharePhotoContent alloc] init];
NSArray<FBSDKSharePhoto *> *photos = @[
  [FBSDKSharePhoto photoWithImage:[UIImage imageNamed:@"thumbs_up.jpg"] userGenerated:YES],
];
content.photos = photos;

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

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

Video Share Example

Swift

// Assuming you have a URL for a PHAsset
let video = ShareVideo(videoURL: assetURL)
let content = ShareVideoContent()
content.video = video

let dialog = MessageDialog(content: content, delegate: self)

// Recommended to validate before trying to display the dialog
do {
    try dialog.validate()
} catch {
    print(error)
}

dialog.show()

Objective-C

// Assuming you have a URL for a PHAsset
FBSDKShareVideoContent *content = [[FBSDKShareVideoContent alloc] init];
content.video = [FBSDKShareVideo videoWithVideoURL:assetURL];

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

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

Android

Prerequisites

Follow the instructions in Sharing on Android, summarized below:

• To use the Facebook Sharing SDK in your project, make it a dependency in Maven, or download it.
• Get a Facebook App ID properly configured and linked to your Android app.
• Configure and link your Facebook app ID to your Page ID with the Messenger Platform tool.
• Generate an Android Key Hash and add it to your developer profile.
• Add a Facebook Activity and include it in your AndroidManifest.xml

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

Related Topic

Sharing to Messenger for the Web