In this document:
Dialogs provide a simple, consistent interface to provide social functionality to your users. Dialogs do not require any additional permissions because they require user interaction. Dialogs can be used by your application in every context: within a Canvas Page, in a Page Tab, in a website or mobile web app, and within native iOS and native Android applications.
There are currently 7 Dialogs available for you to use:
You can integrate Dialogs into your application by constructing the URLs documented below, or by using a helper method in one of the Facebook SDKs:
If you're not using one of the Facebook SDKs, you can invoke a Dialog by redirecting the user's browser to a URL. Every dialog has a method name and parameters. The URL to a dialog always starts with
followed by the name of the dialog and parameters. For example, to ask a user to post a story to their Wall, send them to the Feed Dialog with required parameters:
http://www.facebook.com/dialog/feed? app_id=YOUR_APP_ID& redirect_uri=YOUR_REDIRECT_URI
Because Dialogs enable simple social interactions, the user must be logged into Facebook to see a dialog. If the user is not already logged in, Facebook will prompt them to login before showing the the Dialog you invoked.
All Dialogs share a few common parameters:
||Yes||Your App ID as shows in your app's settings.|
||Yes||The URL to redirect to after the user clicks a button on the Dialog.|
|| No. Default is
||Display mode in which to render the Dialog. See below for more information.|
||No|| If this is set to
Platform Dialogs are all built to seamlessly run in a variety of display contexts on both the web and mobile web. If you're invoking a Dialog using the JS, iOS or Android SDKs, the display mode will be automatically chosen for you based on the platform and the device being used by the user. However, you can force a particular display mode by setting the
display parameter to one of the following values:
page: By default, dialogs run in full-page mode with a Facebook header and footer. This is appropriate for apps that do a full-page redirect in a normal desktop/laptop web browser.
popup: For use in a browser popup no bigger than 400px by 580px. Use this display type to maintain context for the user without needing to perform a full-page redirect.
touch: For use on smartphones, mobile devices and small tablets (such as those with screens under 7 inches).
iframe: For use by apps when running inside an iframe within a Canvas page on Facebook. Displays the dialog within a lightbox-style overlay. Because of the risk of clickjacking, this is only allowed for some certain dialogs, and requires you to pass a valid
access_token. This mode is not supported by the Login Dialog.
async: For use only when loading a dialog via the JS SDK from within a Canvas or Page Tab App. Using
asyncloads the dialog in a modal window.
asyncis the default display mode within Canvas and Page Tab Apps.
On m.facebook.com, no display is needed, nor is any other display than 'touch' allowed as we always default to 'touch'.
The most common error when using a dialog is caused by your app being in sandbox mode. When your app is in sandbox mode, only a developer can post stories with that app id. Here's what the error looks like:
To take your app out of sandbox mode, visit your app's app dashboard and in the basic settings you'll find the option to turn off sandbox mode:
The Add Page Tab Dialog prompts the user to add an app to a Facebook Page that the user admins. This does not require any extended permissions.
Prompt people to publish an individual story to a profile's feed.
Prompt the user to add a friend.
Prompt people to authorize and grant your app permissions
Prompt a payment
Prompt the user to send a message to a friend, group or email address