Real Time Updates for Page Conversations

Real Time Updates allow developers to get notifications on changes without having to constantly ping our servers for changes (which commonly leads to rate limiting).

Today, we'd like to announce that we've recently added a new subscription option for pages: conversations. Developers will be able to subscribe to a page's conversations so that their applications can be notified whenever a message is sent to the page. I'm going to walk through setting up the subscription and the sample application that will handle our push notification.

Please note that creating the subscription uses the Facebook Graph API. In the examples below, I will be leveraging the Facebook PHP SDK.

use Facebook\FacebookSession;
use Facebook\FacebookRequest;

$session = new FacebookSession('<APP_ACCESS_TOKEN>');
$request = new FacebookRequest(
$session,
'POST',
'/<APP_ID>/subscriptions',
array(
'object' => 'page',
'callback_url' => '<YOUR_CALLBACK_URL>',
'fields' => 'conversations',
'verify_token' => '<YOUR_VERIFY_TOKEN>',
)
);
$response = $request->execute();

curl \
-F "object=page" \
-F "callback_url=<YOUR_CALLBACK_URL>" \
-F "fields=conversations" \
-F "verify_token=<YOUR_VERIFY_TOKEN>" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<APP_ID>/subscriptions"

My callback URL points to the following file below. Note that I use error_log() for the input values. This allows me to tail the PHP error log to see the requests as they come in. You're free to store the data however you like, but this is an easy way to get started and see what the responses look like.

<?php

echo $_REQUEST['hub_challenge'];

$inputJSON = file_get_contents('php://input');
$input = json_decode($inputJSON, true);
error_log(print_r($input, true));

After a few seconds of my page receiving a message, a notification is pushed to my callback URL, this is what comes in through my logs:

Array (
[object] => page
[entry] => Array (
[0] => Array (
[uid] => 626011956865
[id] => 626011956865
[time] => 1418284857
[changes] => Array (
[0] => Array (
[field] => conversations
[value] => Array (
[page_id] => 518157959452399,
[conversation_id] => 93054285730295240750,
)
)
)
)
)
)

The following is an example of how you can build your callback URL to handle this notification and re-fetch the updated conversation.

<?php

// php-sdk-v4 loaded in through composer.
require_once 'vendor/autoload.php';

use Facebook\FacebookRequest;
use Facebook\FacebookSession;

FacebookSession::setDefaultApplication('<APP_ID>', '<APP_SECRET>');
// Note that the page access token provided must have
// the read_page_mailboxes permission.
$session = new FacebookSession('<PAGE_ACCESS_TOKEN>');

// Verifying the verify_token ensures nobody else can
// subscribe random things to your application.
if ($_REQUEST['hub_verify_token'] === '<YOUR_VERIFY_TOKEN>') {
echo $_REQUEST['hub_challenge'];
exit;
}

$inputJSON = file_get_contents('php://input');
$input = json_decode($inputJSON, true);

$page_id = $input['entry'][0]['changes'][0]['value']['page_id'];�
$conversation_id = $input['entry'][0]['changes'][0]['value']['conversation_id'];
$field = $input['entry'][0]['changes'][0]['value']['field'];�

switch ($field) {
case 'conversations':
$request = new FacebookRequest(
$session,
'GET',
'/' . $page_id . '/conversations'
);
$response = $request->execute();
$conversations = $response->getGraphObjectList();

foreach ($conversations as $conversation) {
$messages = $conversation->getProperty('messages')->asArray();
foreach ($messages['data'] as $message) {
// Again just using error_log so I can tail my log file.
error_log(sprintf(
"%s sent by %s (%s)",
$message->message,
$message->from->name,
$message->from->id
));
}
}
break;
}

Other Updates for Pages

• Our promotable_posts endpoint can now be filtered by type.
• You can now retrieve promotable posts created using object_story_spec using the is_inline parameter.