Share Dialog

The Share dialog gives people the ability to publish an individual story to their timeline, a friend's timeline, a group, or in a private message on Messenger. This does not require Facebook Login or any extended permissions, so it is the easiest way to enable sharing on the web.

If people are in a browser that is not logged in with a cookie, the drop-down list for choosing the audience for your share doesn't appear. This is also true if the app uses the feed dialog instead of the share dialog or if the app uses iframe web view.

To implement the Share Dialog in native mobile apps read our guides for iOS and Android.

Integration

The Share dialog is available in the Facebook SDK for JavaScript. You can use the following code snippet to trigger the Share dialog. You can also use a redirect to a URL. For details, see Advanced Topics.

Facebook SDK for JavaScript

Trigger a Share Dialog using the FB.ui function with the share method parameter to share a link.

To share a link:

FB.ui({
  method: 'share',
  href: 'https://developers.facebook.com/docs/',
}, function(response){});
Try it yourself!

Include open graph meta tags on the page at this URL to customize the story that is shared back to Facebook.

Note that response.error_message will appear only if someone using your app has authenciated your app with Facebook Login.

Parameters

Common Parameters

The JS SDK will provide these parameters automatically.

Parameter Description

app_id

Your app's unique identifier. Required.

redirect_uri

The URL to redirect to after a person clicks a button on the dialog. Required when using URL redirection.

display

Determines how the dialog is rendered.

  • If you are using the URL redirect dialog implementation, then this will be a full page display, shown within Facebook.com. This display type is called page.
  • If you are using one of our iOS or Android SDKs to invoke the dialog, this is automatically specified and chooses an appropriate display type for the device.
  • If you are using the Facebook SDK for JavaScript, this will default to a modal iframe type for people logged into your app or async when using within a game on Facebook.com, and a popup window for everyone else. You can also force the popup type when when you use the Facebook SDK for JavaScript, if necessary.
  • Mobile web apps will always default to the touch display type.

share Parameters

Parameter Description Default

href

The link attached to this post. Required when using method share. Include open graph meta tags in the page at this URL to customize the story that is shared.

Current URL

hashtag

A hashtag specified by the developer to be added to the shared content. People will still have the opportunity to remove this hashtag in the dialog. The hashtag should include the hash symbol, e.g. #facebook.

null

quote

A quote to be shared along with the link, either highlighted by the user or predefined by the developer, as in a pull quote on an article.

null

mobile_iframe

If set to true the share button will open the share dialog in an iframe on top of your website (For more information see Mobile Web Share Dialog. This option is only available for mobile, not desktop.

false


Response Data

Parameter Description

post_id

Only available if the user is logged into your app using Facebook and has granted publish_actions. If present, this is the ID of the published Open Graph story.

error_message

Only available if the user is logged into your app using Facebook Login.

Advanced Topics

You can also take advantage of the following advanced features.

Mobile Web Share Dialog

The mobile web share dialog also has the ability to be show in an iFrame on top of your content. If a person finishes the sharing flow, the dialog will dismiss and leave them back to the original piece of content so they can easily continue consuming it.

Code Example

To enable the mobile web share dialog in an iframe, set the attribute mobile_iframe to true:

FB.ui({
  method: 'share',
  mobile_iframe: true,
  href: 'https://developers.facebook.com/docs/',
}, function(response){});
Try it yourself!

URL Redirection

To share a link:

https://www.facebook.com/dialog/share?
  app_id=145634995501895
  &display=popup
  &href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2F
  &redirect_uri=https%3A%2F%2Fdevelopers.facebook.com%2Ftools%2Fexplorer

Note: When testing this code, remove the line breaks. Otherwise you will run into an error.

Open Graph actions

Trigger a Share Dialog using the FB.ui function with the share_open_graph method parameter to share an Open Graph story.

To share an Open Graph story with the dialog:

FB.ui({
  method: 'share_open_graph',
  action_type: 'og.likes',
  action_properties: JSON.stringify({
    object:'https://developers.facebook.com/docs/',
  })
}, function(response){});

Note that URL redirection works the same way as for standard link shares.

share_open_graph Parameters

Use the same parameters as for sharing a standard link, but add the following:

Parameter Description

action_type

A string specifying which Open Graph action type to publish, e.g., og.likes for the built in like type. The dialog also supports approved custom types. Required when using method share_open_graph.

action_properties

A JSON object of key/value pairs specifying parameters which correspond to the action_type being used. Valid key/value pairs are the same parameters that can be used when publishing Open Graph Actions using the API. Required when using method share_open_graph.

The share_open_graph dialog does not support mobile_iframe: true.