Game Gifting API

Gifts are typically lightweight virtual goods (energy packs, vanity items) that can be used to re-engage players who haven't played your game in a while. Many games implement the feature that players can easily accept pending gifts and send reciprocal gifts back to their friends. This creates a retention loop that encourages players to stay engaged in your game.

Creating objects for requests

To send an object and action as part of a request, you'll need to create an Open Graph representation of an in-game item that can be sent in requests.

Open Graph objects for requests can be created in the same way as objects for custom Open Graph stories. You can even re-use the same objects that you use in your stories if you'd like. However, you cannot use instances of the standard open graph types and must use your own custom open graph type.

It is a requirement that objects sent via requests need to be app-owned, so they are public for everyone to see.

You will need to set up a custom Open Graph object type, and an instance of that type, for each type of object you would like to use in a request. For example, if you are sending a bomb and a life, you will set up an Open Graph object type for a bomb and another one for a life, and create an instance of type.

To create a custom Open Graph type, follow the instructions in the "Creating Object Types" documentation. Or follow steps below:

Open your App Dashboard and navigate to the Open Grah section.


Click Add Object Type button, and create the bomb type.


Here is the object type for the bomb example used elsewhere in this guide. The only required properties are og:type and og:title.


Other properties (image, description etc.) of the object instance are not used in requests. The information shown in the request is based on the object type name.

The Object Brower tool is an easy and fast way to create the object instances.

Creating an instance of a bomb object type using the Object Browser is showed below:


Note:  If you want attach an image to your object,  you should add image URL to the og:image field. Here are Facebook recommendations due to object image :

The URL of an image which is used in stories published about this object. We suggest that you give us an image of at least 600x315 pixels. However, bigger is better, so if you have a 1200x630 or larger image that you can use, please give it to us. Also, we recommend that you keep images as close to a 1.91:1 aspect ratio as possible to avoid cropping. (Note: image sizes must be no more than 5MB in size.) For games, images should be square and at least 600x600 pixels. Note that you can include more than that one og:image in your object if you have more than one resolution available. It's possible to update an open graph object. If you want to update the image for an open graph object after it's been published, we strongly suggest that you use a new URL for the new image. Images are cached based on the URL and may not be updated unless the URL used in the object description changes.


Sending Gifts

Now you are ready to send some gifts. You need to get bomb object id, which you have got in Object Browser:


The following code snippet shows how to send a bomb item. By default, the sender is presented with a multi-friend selector allowing to select a maximum of 50 recipients.  

private string BombItemId = "993386627342473";

public void SendItem() {
	SPFacebook.instance.SendGift("Sample Titile", "Sample message", BombItemId);


Sending requests to a specific recipient and providing additional request data:

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

private string BombItemId = "993386627342473";

public void SendToSpecifiedFriend() {
	string FriendId = "1405568046403868";
	SPFacebook.instance.SendGift("Sample Titile", "Sample message", BombItemId, "some_request_dara", new string[]{FriendId});


Asking for help

You can ask gifts from the friends the same way you are sending them.

When a player gets stuck in your game, he can use Requests to ask his friends for assistance by requesting specific items. Similar to gifting, this also creates an organic retention loop that encourages players to stay engaged in your game.


The following code snippet shows the way we can ask friend for help.

private string BombItemId = "993386627342473";

public void SendToSpecifiedFriend() {
    SPFacebook.instance.AskGift("Sample Titile", "Sample message", BombItemId);


With a specific recipient and providing additional request data:

private string BombItemId = "993386627342473";

public void SendToSpecifiedFriend() {
	string FriendId = "1405568046403868";
	SPFacebook.instance.AskGift("Sample Titile", "Sample message", BombItemId, "some_request_dara", new string[]{FriendId});


Handling requests result

When a request has been sent via the Request dialog, a response will be passed to the callback containing the FBAppRequestResult object. The following code snippet  shows how to subscribe on the result callback and parse result data:

private string BombItemId = "993386627342473";

public void SendToSpecifiedFriend() {
	string FriendId = "1405568046403868";
	SPFacebook.instance.SendGift("Sample Titile", "Sample message", BombItemId, "some_request_dara", new string[]{FriendId});
	SPFacebook.instance.OnAppRequestCompleteAction += OnAppRequestCompleteAction;

void OnAppRequestCompleteAction (FBAppRequestResult result) {

	if(result.IsSucceeded) {
		Debug.Log("App request succeeded");
		Debug.Log("ReuqetsId: " + result.ReuqestId);
		foreach(string UserId in result.Recipients) {

		Debug.Log("Original Facebook Response: " + result.Result.Text);
	} else {
		Debug.Log("App request has failed");

	SPFacebook.instance.OnAppRequestCompleteAction -= OnAppRequestCompleteAction;


The request result is represented as the FBAppRequestResult object.

public class FBAppRequestResult  {

	//FB result from Unity Facebok SDK
	public FBResult Result {get;}

	//The request object ID. 
	public string ReuqestId {get;}

	//An array of the recipient user IDs for the request that was created.
	public List<string> Recipients {get;}

	//Flag to indicate of request was sent successfully
	public bool IsSucceeded {get;}


Accepting a request

When a recipient accepts a request, either through the notification jewel, the beeper popup, your application will be launched or user will be redirected to the Google Play or iTunes application page.


Reading requests

In order to read all the requests for a recipient,  you can query the graph as shown below:

public void RetriveAppRequests() {
	SPFacebook.instance.OnAppRequestsLoaded += OnAppRequestsLoaded;

void OnAppRequestsLoaded (FBResult result) {
	if(result.Error ==  null) {

		//Printing all pending request's id's
		foreach(FBAppRequest request in SPFacebook.instance.AppRequests) {
    SPFacebook.instance.OnAppRequestsLoaded -= OnAppRequestsLoaded;


The app request is represented as FBAppRequest object.


public class FBAppRequest {

	//Unique request id
	public string Id {get;}

	//Your app's unique identifier.
	public string ApplicationId {get;}
	//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
	public string Message {get;}

	//Request Type. Used when defining additional context about the nature of the request. Possible values are Send, AskFor, Turn and Undefined
	public FBAppRequestActionType ActionType {get;}

	//Request State. Used to defining of request was already removed. Possible values are Pending and Deleted
	public FBAppRequestState State {get;}

	//Sender Facebook ID
	public string FromId {get;}

	//Sender Name
	public string FromName {get;}
	//Request Created Time
	public DateTime CreatedTime;
	public string CreatedTimeString {get;}

	//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. (Optional)
	public string Data {get;}

	//The Open Graph object being sent. Only if ActionType has been set to Send or AskFor 
	public FBObject Object {get;}


public enum FBAppRequestActionType {


public enum FBAppRequestState  {


Available Only if ActionType has been set to Send or AskFor

public class FBObject  {

	//The Open Graph object ID of the object being sent.
	public string Id {get;}

	//Object image url's
	public List<string> ImageUrls {get;}

	//Object title
	public string Title {get;}

	//Object type
	public string Type {get;}

	//Object created time
	public DateTime CreatedTime {get;}
	public string CreatedTimeString {get;}


After information about the request is retrieved,  you can process app requests according to the request type and content.

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 Delete methods of the FBAppRequest object.

Note: After the request has been deleted successfully, it will not be removed from the  SPFacebook.instance.AppRequests array. But the request state will be changed to Deleted. The following code sample shows how to delete one of the user app requests:

//asuming we have more that one reqeust in the AppRequests array
FBAppRequest app_request = SPFacebook.instance.AppRequests[0];

// Processing request code

app_request.OnDeleteRequestFinished += OnDeleteRequestFinished;

void OnDeleteRequestFinished (FBResult res) {
	if(res.Error == null) {
		Debug.Log("Request Removed!");


Rewarding the Sender

In efforts to incentive players to send requests, you can reward the sender based on certain actions the receiver performs as a result. For example, you cannot 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 will be able to reward the sender. In order to do this, you will want to trace a request back to the sender to know who to give a reward. There are two ways to achieve this:

  1. Upon sending the request, store the request id returned in the response from the request dialog and match it upon receipt to reward the sender.

  2. Read all the requests for the receiver and reward the sender based on the ID in the "from" field.


Translating Requests

Requests can be translated and depended on the type of request, this is done by either Facebook or the developer. Please, see the Translation Guide for Requests for the details.


You can read more about the Facebook App requests at the Facebook Official Documentation. The implementation example can be found at the FacebookTurnBasedAndGifts example scene.