Dialogs Overview

Dialogs

In this document:

Overview
Invoking a Dialog directly with a URL
Common Dialog Parameters
Errors

Overview

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:

The Feed Dialog allows a user to post a story to their Timeline and to their friends' News Feeds
The Login Dialog allows a user to authorize an application as part of an authentication flow.
The Add Page Tab Dialog allows a user to add an application to a Facebook Page which they administer.
The Friends Dialog allows a user to send a friend request to another user.
The Pay Dialog allows a user to make a purchase using Facebook Credits.
The Requests Dialog allows a user to send a request to one or more of their friends
The Send Dialog allows a user to send a Facebook Message to one or more of their friends.

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:

JavaScript SDK using the FB.ui method.
iOS SDK using the FBWebDialogs class methods.
Android SDK using the WebDialog class methods.

Invoking a Dialog directly with a URL

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

      http://www.facebook.com/dialog/

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.

Common Dialog Parameters

All Dialogs share a few common parameters:

Name	Required?	Description
`app_id`	Yes	Your App ID as shows in your app's settings.
`redirect_uri`	Yes	The URL to redirect to after the user clicks a button on the Dialog.
`display`	No. Default is `page`	Display mode in which to render the Dialog. See below for more information.
`show_error`	No	If this is set to `true`, the error code and error description will be displayed in the event of an error.

Display Modes

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 async loads the dialog in a modal window. async is 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'.

Errors

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: