Requests Dialog

Dialogs

Overview

The Request Dialog sends a Request from one user (the sender) to one or more users (the recipients). The Request Dialog can be used to send a Request directly from one user to another or display a Multi Friend Selector Dialog, allowing the sending user to select multiple recipient users.

This documentation covers the Request Dialog API. For more information on the full set of features available to Requests including how recipient users interact with a Request be sure to check out the Requests Docs.

Requests are only available for Desktop Canvas, iOS and Android apps. Accepting a request on Canvas will direct the user to the Canvas Page URL of the app that sent the Request. For native mobile apps, accepting the request will direct the user to the app on their device if installed or to the appropriate location (Apple App Store or Google Play) to download the app otherwise.

JavaScript Example

This example uses the JavaScript SDK to render a modal Requests Dialog and assumes the user has already installed the application.

<html xmlns="http://www.w3.org/1999/xhtml"
  xmlns:fb="https://www.facebook.com/2008/fbml">
  <head>
    <title>Request Example</title>
  </head>

  <body>
    <div id="fb-root"></div>
    <script src="http://connect.facebook.net/en_US/all.js"></script>
    <p>
      <input type="button"
        onclick="sendRequestToRecipients(); return false;"
        value="Send Request to Users Directly"
      />
      <input type="text" value="User ID" name="user_ids" />
      </p>
    <p>
    <input type="button"
      onclick="sendRequestViaMultiFriendSelector(); return false;"
      value="Send Request to Many Users with MFS"
    />
    </p>
    
    <script>
      FB.init({
        appId  : 'YOUR_APP_ID',
        frictionlessRequests: true
      });

      function sendRequestToRecipients() {
        var user_ids = document.getElementsByName("user_ids")[0].value;
        FB.ui({method: 'apprequests',
          message: 'My Great Request',
          to: user_ids
        }, requestCallback);
      }

      function sendRequestViaMultiFriendSelector() {
        FB.ui({method: 'apprequests',
          message: 'My Great Request'
        }, requestCallback);
      }
      
      function requestCallback(response) {
        // Handle callback here
      }
    </script>
  </body>
</html>

Sending Requests

You can send Requests to a set of users by specifying their User ID or allow a user to select the recipients using the multi-friend selector.

Send a Request to One or More Users

To send a request to a single user you will need to invoke the Request Dialog with the to parameter and use it to include the User ID of the recipient user. See below:

function sendRequestToRecipients() {
  FB.ui({method: 'apprequests',
    message: 'My Great Request',
    to: '499802820'
  }, requestCallback);
}

You can pass an array or comma delimited string of User IDs to send a Request to multiple users:

function sendRequestToRecipients() {
  FB.ui({method: 'apprequests',
    message: 'My Great Request',
    to: '499802820,499802852'
  }, requestCallback);
}

The user will see a dialog that looks like the following, allowing them to send a Request to the target user(s):

Enabling the Multi Friend Selector Dialog for Requests

To enable the user to select who they would like to send a request to you can invoke the Request Dialog as below (notice the absence of the to parameter):

function sendRequestViaMultiFriendSelector() {
  FB.ui({method: 'apprequests',
    message: 'My Great Request'
  }, requestCallback);
}

The user will see the Multi Friend Selector Dialog, allowing them to select the recipient users of the Request. A user is limited to selecting 50 recipients at a time (and 25 recipients if they are using IE6/7).

Frictionless Requests

Frictionless Requests enable users to send Requests to specific friends from within an app without having to click on a pop-up confirmation dialog. Upon sending a Request to a friend from within an app, a user may authorize the app to send subsequent Requests to the same friend without a Dialog prompt. This removes a Dialog from the flow and streamlines the process of sharing with friends.

As a best practice Canvas developers should always enable Frictionless Requests.

To enable Frictionless Requests you must initialize the JavaScript SDK with the ‘frictionlessRequests:true’ option in FB.init. You send Requests to users via the Requests Dialog just as before. As users share with friends, they may authorize the app to send future requests to specific friends on their behalf.

If you are sending a Request to multiple recipients and all of the user IDs are frictionless, the confirmation dialog will not display and the users will be notified of the Request. If one or more of the recipients are not frictionless, the confirmation dialog will be displayed and the user must press ‘Send Request’ for the Request to be sent.

Building on the JavaScript example from above, add ‘frictionlessRequests:true’ to the FB.init call to enable Frictionless Requests:

FB.init({
  appId  : 'YOUR_APP_ID',
  frictionlessRequests : true
});

Frictionless Requests are supported with the Javascript SDK on Desktop Canvas and mobile web as well as with the iOS and android SDKs on native mobile apps.

Direct URL Example

This example uses the the raw URL to render a Request Dialog for your app. One key difference from using this method over the JavaScript SDK is the requirement of the redirect_uri parameter.

http://www.facebook.com/dialog/apprequests?
  app_id=APP_ID&
  message=Facebook%20Dialogs%20are%20so%20easy!&
  redirect_uri=http://www.example.com/response

After the user follows the flow and sends the request the browser will redirect to

http://example.com/response?request=REQUEST_ID&to=ARRAY_OF_USER_IDS

If there are errors, the browser will redirect to

http://example.com/response?error_code=ERROR_CODE&error_msg=ERROR_MSG

Properties

`app_id`	Your application's identifier. Required, but automatically specified by most SDKs.
`redirect_uri`	The URL to redirect to after the user clicks a button on the dialog. Required, but automatically specified by most SDKs.
`message`	The Request string the receiving user will see. It appears as a request posed by the sending user. The maximum length is 130 characters for English language and 85 characters for other launguages. The message value is displayed in Notifications and can also be viewed on the App Center Requests. Invites (requests where the recipient has not installed the app) do not display this value.
`to`	A user ID or username. This may or may not be a friend of the user. If this is specified, the user will not have a choice of recipients. If this is omitted, the user will see a Multi Friend Selector and will be able to select a maximum of 50 recipients. (Due to URL length restrictions, the maximum number of recipients is 25 in IE7/IE8 when using a non-iframe dialog.)
`filters`	Optional, default is '', which shows a Multi Friend Selector that includes the ability for a user to browse all friends, but also filter to friends using the application and friends not using the application. Can also be `all`, `app_users` and `app_non_users`. This controls what set of friends the user sees if a Multi Friend Selector is shown. If `all`, `app_users` ,or `app_non_users` is specified, the user will only be able to see users in that list and will not be able to filter to another list. Additionally, an application can suggest custom filters as dictionaries with a `name` key and a `user_ids` key, which respectively have values that are a string and a list of user IDs. `name` is the name of the custom filter that will show in the selector. `user_ids` is the list of friends to include, in the order they are to appear. Example #1 [{name: 'Neighbors', user_ids: [1, 2, 3]}, {name: 'Other Set', user_ids: [4,5,6]}] Example #2 ['app_users'] Note: the filters option is disabled on mobile dialogs and will not affect the set of users that appear in the dialog.
`exclude_ids`	A array of user IDs that will be excluded from the Dialog, for example: exclude_ids: [1, 2, 3] If a user is excluded from the Dialog, the user will not show in the Multi Friend Selector. This parameter is not supported on mobile devices.
`max_recipients`	An integer that specifies the maximum number of friends that can be chosen by the user in the friend selector. This parameter is not supported on mobile devices.
`data`	Optional, additional data you may pass for tracking. This will be stored as part of the request objects created. The maximum length is 255 characters.
`title`	Optional, the title for the Dialog. Maximum length is 50 characters.

For a list of properties that are common to all Dialogs, please check out the Dialogs Documentation.

Return Data

`request`	The Request Object ID. To get the full Request ID, concatenate this with a user ID from the `to` field: `‘<request_object_id>_<user_id>’`
`to`	An `array` of the recipient user IDs for the request that was created.

Updated about a month ago