Upgrade to Requests 2.0
By Jared Morgenstern
Requests and Bookmarks help users more easily reengage with apps they use. Whenever a user has an action to take within an app, a counter appears next to the bookmark.
Instead of manually managing the bookmark count using the incrementCount and decrementCount APIs, we’re unifying our APIs so the count represents the number of all outstanding requests. This means that as a developer, you only need to worry about one way of updating users about outstanding items in your app - send requests.
Sending Requests
Requests are a great way to enable users to invite their friends, accept a gift or help them complete a mission in your app. There are now two types of requests that can be sent from an app:
- User-generated requests: These requests are confirmed by a user’s explicit action on a request dialog. These requests update the bookmark count for the recipient. You send requests by using the recently launched Request Dialog.
- App-generated requests: These requests can be initiated and sent only to users who have authorized your app. Developers can send these requests using the Graph API. Use these requests to update the bookmark count to encourage a user to re-engage in the app (e.g., your friend finished her move in a game and it’s now your turn).
To use both request types and automatically sync the bookmark count to them, enable “Upgrade to Requests 2.0” in your Developer App settings on the “Advanced” tab. This switch controls the bookmark counts seen by your users and synchronizes the count with sent requests.
HTML/JavaScript example of a user-generated request:
<html>
<head>
<title>My Great Website</title>
</head>
<body>
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js">
</script>
<script>
FB.init({
appId:'YOUR_APP_ID', cookie:true,
status:true, xfbml:true
});
FB.ui({ method: 'apprequests',
message: 'Here is a new Requests dialog...'});
</script>
</body>
</html>
Which will display the following to the user: 
PHP example of an app-generated request:
<?php
$app_id = YOUR_APP_ID;
$app_secret = YOUR_APP_SECRET;
$token_url = "https://graph.facebook.com/oauth/access_token?" .
"client_id=" . $app_id .
"&client_secret=" . $app_secret .
"&grant_type=client_credentials";
$app_access_token = file_get_contents($token_url);
$user_id = THE_CURRENT_USER_ID;
$apprequest_url ="https://graph.facebook.com/" .
$user_id .
"/apprequests?message=’INSERT_UT8_STRING_MSG’" .
"&data=’INSERT_STRING_DATA’&" .
$app_access_token . “&method=post”;
$result = file_get_contents($apprequest_url);
echo(“Request id number: ”, $result);
?>
The message parameter is a UTF-8 string which describes the request. The data parameter is a string which the app can use to store any relevant data in order to process the request.
Processing requests
When a user arrives within your app (via bookmark, notification, etc.), you should first read the outstanding app requests for that user. Then, potentially highlight the request the user wants to act upon and delete requests when the user acts upon them (either ignores or handles them).
PHP example for reading, printing, and deleting requests:
<?php
$app_id = 'YOUR_APP_ID';
$app_secret = 'YOUR_APP_SECRET';
$token_url = "https://graph.facebook.com/oauth/access_token?" .
"client_id=" . $app_id .
"&client_secret=" . $app_secret .
"&grant_type=client_credentials";
$access_token = file_get_contents($token_url);
$signed_request = $_REQUEST["signed_request"];
list($encoded_sig, $payload) = explode('.', $signed_request, 2);
$data = json_decode(base64_decode(strtr($payload, '-_', '+/')), true);
$user_id = $data["user_id"];
//Get all app requests for user
$request_url ="https://graph.facebook.com/" .
$user_id . "/apprequests?" .
$access_token;
$requests = file_get_contents($request_url);
//Print all outstanding app requests
echo '<pre>';
print_r($requests);
echo '</pre>';
//Process and delete app requests
$data = json_decode($requests);
foreach($data->data as $item) {
$id = $item->id;
$delete_url = "https://graph.facebook.com/" .
$id . "?" . $access_token . "&method=delete";
$result = file_get_contents($delete_url);
echo("Requests deleted? " . $result);
}
?>
The JSON requests data is printed below (note that presence of the from field in the request that is a user-generated request):
{
"data":[
{
"id":"167548189960088",
"application":{
"name":"Cat's Test Site",
"id":"314268391344"
},
"to":{
"name":"Cissy Lim",
"id":"100001147247007"
},
"data":"'INSERT_STRING_DATA'",
"message":"'INSERT_UT8_STRING_MSG'",
"created_time":"2011-02-16T08:37:02+0000"
},
{
"id":"167546793293561",
"application":{
"name":"Cat's Test Site",
"id":"314268391344"
},
"to":{
"name":"Cissy Lim",
"id":"100001147247007"
},
"from":{
"name":"Cat Lee",
"id":"220400"
},
"message":"Here is a new Requests dialog...",
"created_time":"2011-02-16T08:21:45+0000"
}
]
}
These requests will auto-expire after fourteen days to ensure a simple, clean user experience.
We believe these improvements will help apps drive more user engagement and encourage all apps to migrate to the new requests model as soon as possible. New apps will automatically use Requests 2.0. Let us know what you think in the comments below.
Get our newsletter
Sign up for monthly updates from Meta for Developers.