Game Requests

Overview

Game requests give players a mechanism for inviting their friends to play a game. Requests are sent by a player to one or more friends, and always carry a call-to-action for the game. Recipients can be existing players or new players.

Game requests can be used to attract new players or to re-engage existing players. Requests can be sent in two scenarios:

  1. The recipient is a friend of the sender and has not authenticated the game. This scenario is useful for invites.
  2. The recipient is a friend of the sender and has authenticated the game before. This scenario is useful for turn-based notifications, gifting, and asking for help.

Requests are sent while the sender is in-game and are surfaced to recipients in several places on Facebook. Requests are always private, and can only be seen by the recipient. While a single request can be sent to multiple recipients at once, the receiver of a request only ever sees details of the sender, and can never see either other recipients of the request.

An example Game Request surfaced on Facebook for Desktop.

Game requests are available for Games on Facebook and for mobile games on iOS and Android. On the Facebook desktop site, requests appear as a beeper pop-up in the lower left of the screen as well as in the notifications jewel, if they are not filtered. On mobile platforms, requests will surface within the list of notifications in the Facebook App, if they are not filtered. Request data is available through the Game Request API, and custom UIs can be built for a more integrated experience within mobile games. Your implementation of requests should therefore be platform-agnostic and should provide a consistent user experience, regardless of platform. However, invites that are sent by the player will appear on whatever combination of platforms supported by your game.

Notes:

  • As of Graph API 2.3, Game requests are only available to games.
  • We filter app requests for spam or other negative signals. We will not send notifications for filtered request. People may find filtered requests in the games activity view.
  • Open Graph custom objects are deprecated in Graph API v2.8. Therefore, only pre-built objects can be used for game requests with Graph API v2.8.

Launching the Request Dialog

The game request dialog is generated via the JavaScript, iOS, Android, and Unity SDK. These examples assume the sender has already authenticated the app. If no recipients are specified, you can filter the list of friends to a limit of 50 friends or less, and you can segment by registered players or unregistered friends. This is useful for providing a separate flow for re-engagement or invitation.

JavaScript

Sending requests using the multi-friend selector provided by the game request Dialog:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

When the dialog is closed, the response object will contain the results of the send, including a request id and an array of to recipients. For example:

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

By default, the sender is presented with a multi-friend selector allowing them to select a maximum of 50 recipients.

Due to URL length restrictions, the maximum number of recipients is 25 in Internet Explorer 7 or 8 when using a non-iframe dialog.

Sending requests to a specific recipient:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

If the to field is specified, the sender will not be able to select additional recipients.

Sending requests to multiple specific recipients:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

Multiple recipients can be specified via a comma-separated list containing User IDs.

There are restrictions on the maximum number of recipients you are able to specify via the to field. Namely, fewer than 50 friends, and fewer than 26 friends on Internet Explorer 8 or below.

Sending requests to specific lists of friends:

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

Sending objects via requests, by explicitly stating an action_type and object_id:

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

For turn based requests, do not specify an object_id.

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

Alternatively, recipients can be divided into named lists, allowing the player to pick from logically-grouped friends based on their status in the game.

For more information, see the FB.ui reference documentation for the Facebook SDK for JavaScript.

iOS SDK

Launching the request dialog using the friend selector provided by the iOS SDK:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Sending requests explicitly stating an action_type and object_id to a specific recipient using the iOS SDK:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Android SDK

Sending a request using the request dialog friend selector via the Android SDK:

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

Sending a request explicitly stating an action and object using the Android SDK:

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

Unity SDK

Here is how requests are done in the Unity SDK. Check the FB.AppRequest documentation for more details.

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

Dialog Parameters

The Game Request Dialog can be created with a number of additional parameters that determine its behavior. These parameters are described below.

Parameter Name Description Required

app_id

Your app's unique identifier.

Yes

redirect_uri

The URL to redirect to after a sender clicks a button on the dialog. Used for returning a sender to the game after sending a request. For security reasons, the redirect_uri specified must exist within the same root domain as the app's Facebook Web Games Page URL.

Yes when using URL Redirection

to

Either a user id,username or invite token, or a comma-separated list of user ids, usernames or invite tokens. These may or may not be a friend of the sender. If this is specified by the app, the sender will not have a choice of recipients. If not, the sender will see a multi-friend selector

No

message

A plain-text message to be sent as part of the request. This text will surface in the App Center view of the request, but not on the notification jewel

Yes

action_type

Used when defining additional context about the nature of the request. Possible values are send, askfor, and turn

Yes if object_id has been set

object_id

The Open Graph object ID of the object being sent.

Yes if action_type has been set to send or askfor

filters

This controls the set of friends someone sees if a multi-friend selector is shown. If left empty, the multi-friend selector will display all of the user's Facebook friends. By specifying app_users, the multi-friend selector will only display friends who are existing users of the app. This should be used when using requests for matchmaking. Alternatively, by specifying app_non_users, the sender will only see friends who have previously not authenticated the app. This should be used when using requests for inviting new users to the game. An app can also suggest custom filters as dictionaries with name and user_ids keys, 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. Note: On the iOS and Android SDKs only the app_users and app_non_users filters are supported, as singular values. Dictionaries of these values are not supported.

No

exclude_ids

An array of user IDs that will be excluded from the dialog. If someone is excluded from the dialog, they will not appear in the multi-friend selector. Note: This parameter is not supported by the mobile SDKs and will be ignored.

No

max_recipients

An integer that specifies the maximum number of friends that can be chosen by the sender in the friend selector. This parameter is not supported on mobile devices.

No

data

Additional freeform data you may pass for tracking. This will be stored as part of the request objects created. The maximum length is 255 characters.

No

title

The title for the Dialog. Maximum length is 50 characters.

No

Response Data

When a request has been sent via the game request dialog, a response will be passed to the callback containing the following information:

Parameter Name Description

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.

Handling Requests In-game

Accepting Requests

When a recipient accepts a request on the Facebook desktop site, they will be sent to the URL of the game that sent the request. This URL will contain an additional GET parameter request_ids, which is a comma-delimited list of request IDs that the user is accepting:

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

Requests are not automatically deleted when a recipient accepts them. This is the responsibility of your game. A common approach is that when your game is launched, read from the Graph API the list of outstanding requests for that user and delete each one after processing.

When a recipient accepts a request on a mobile platform, this will deep-link to the app. An additional parameter will be present in the loading of the app, the request ID. The same responsibility of accepting and clearing requests applies on mobile as well. It's a good practice to check and clear pending requests on game launch.

Reading requests

Each request sent has a unique request object ID. This ID represents the request object. This request object ID can be concatenated with a recipient user ID to create a specific instance of the request. The represents one instantiation of the request, which was sent to a specific recipient.

For example, when sending a request, the response from the Game Request Dialog looks like the following:

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

If you look up the request object ID via the Graph API, the response you receive will differ slightly, depending on the viewing context of the lookup, but the response will always represent the entire request object.

For example, if a query to http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN is made with the user access token of the recipient, you will see the following response:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Note that both the to and from fields are returned. However, if the same endpoint is called using the access token of the sender, or an app access token, Facebook will return the following:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

To get the full request that includes the recipient using an app access token, you will need to append the recipient user ID following an underscore '_' character. So for example, a call to https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} returns:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Reading all requests

In order to read all the requests for a recipient for you can query the graph as shown below using the recipient's USER ACCESS TOKEN. This will return a list of request ids for that user in the app.

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

Deleting Requests

Game Requests are not automatically deleted after they have been accepted by the recipient. It is the responsibility of the developer to delete the request after it has been accepted. You must delete requests on behalf of players once they have been accepted.

You can delete a request via the following methods:

Graph API

Issue an HTTP DELETE request to the concatenated request_id:

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

Tracking Requests for referrals and rewards

You can reward the Game Request sender based on certain actions the receiver performs as a result. For example, you can not reward players for simply sending requests, but if the receiver installs the game and reaches a certain level as a result of accepting the request, you are able to reward the sender.

In order to reward the sender, you will need to know who to reward. There are two ways to achieve this:

  1. When sending the request, store the request_id returned in the response from the game request dialog and match it upon receipt to reward the sender.
  2. Read all the requests for a player when they've launched the game, and reward the sender based on the id in the from field of their requests. If multiple friends have invited a player, you can choose to reward the first or all senders.

Invitable Friends API

The Invitable Friends API is no longer usable with game requests. It now returns empty data and will be deprecated in the near future.

Localization

To help you offer the best user experience for your global audience, Facebook supports localization for requests. Before you translate requests, it’s important to know the different types of requests and how they are surfaced. Requests can be seen as the standard “Anita sent you a request” or if an action/object pair is specified, “Anita asked you for a Life” or “Anita sent you a Bomb”. There is also a turn request letting people know that it is their turn in a game versus their friend. All of those examples are seen by players that have authed the game. If the recipient doesn’t have the game installed, he will see the request in the form of an invite. For example, “Anita invited you to play Friend Smash!”. Let’s take a look at how to translate each one of these.

Translating Invites

The text for an invite is automatically translated by Facebook and cannot be controlled by developers. It is translated into the language of the recipient.

Invite Notification in English
Invite Notification in Thai

Notice in the examples above that the text “invited you to play” is automatically translated into the other language, in this case Thai. The app name and description are translated in the “Localize” section of the app settings as “Display Name” and "Description", in the yellow boxes below.

Translating the App's Display Name and Description

Requests can also show up in the App Center. In the App Center, the “message” of the request is displayed. The message can be translated by the developer. In the examples below, the message is "Can I have a life to help me through the next level?" in English and "ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" in Thai. Currently the main text for the request, "Anita sent you a request" is not shown in App Center.

Request in App Center in English
Request in App Center in Thai

Translating the Message

Since the message is passed in as a parameter when the request dialog is invoked, you can translate this on your own before you invoke the request dialog and pass in the translated string as the message. If you want to change the translation dynamically, you should do so before you invoke the dialog. It is up to you to decide which language you would like to display as this will be the same text that the sender sees in the request preview and the recipient sees upon receiving the request.

Many developers detect the locale of the sender and then use that to determine what language to use as the message. They assume that in most cases the sender and recipient speak the same language. In the example above, you could look at the locale of the sender and if it was Thai, you could send in the string in Thai directly as the message, like this:

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

Best Practices

Appending data to a request

As mentioned in the Dialog Parameters section above, you are able to append up to 255 characters of additional data to send with the request. You can use this facility to either transfer additional information regarding the request, or append an identifier that you can use later to look up relevant information stored on your server.

As an example, in the Facebook sample game project Friend Smash, players take turns competing to 'smash' the highest number of friends possible. When one player sends a challenge to another, via a request, the data parameter is used to store the challenging player's latest score. The game then extracts this value for the receiving player, and makes it the target score for the next game.

Filter invites

When building a custom multi-friend selector, or otherwise choosing who to send requests to, consider providing filters to help the player choose their desired recipients.

A common filter used when implementing invites using the game request dialog is the app_non_users filter. This filter prevents the game request dialog from displaying people who have previously played your game. Other filters you may consider are players recently interacted with or players of similar games you control. For a full list of filters available, see the game request dialog - parameters reference doc.

Create engaging mechanisms

Create engaging mechanisms for players when they visit their friends in game or interact with them directly. For example, if the game supports the concept of neighbors, grant bonus energy when players visit their neighbors' environments. If a player's base is attacked, let their friends help repair it. Players generally find value in helping their friends progress, and giving them opportunities to do so results in greater social experience and more people playing.

Make the object valuable to the player

Offer something that is valuable to the player that they can use to enhance their gameplay or social experience.

Segment players and offer requests in context

Evaluate your players and break them up into various groups that make sense for your game (e.g. new players, players that are doing crafting, players with lots of friends, engaged players, etc.). Think about what kinds of things would be useful to them at their level, and offer specific things to each segment.