Game Updates via Messenger

Facebook Games can use Messenger as a channel for their Game Updates. This is an optional but highly recommended channel, and it gives your game a powerful channel for re-engagement. Here's how to create and set up your Game Updates via Messenger:

Step 1: Create a Page

To create a Game Update via Messenger, you'll first need to create a Facebook page. In order for the page to work correctly with your Instant Game it needs meet some specific criteria:

  • The page's category must be App Page or Video Game (and only these categories)
  • The page's name needs to contain the name of the app.
  • The page cannot be associated with another app.

To create a page with these criteria, visit your App Dashboard and follow these steps:

  1. In the Product menu, expand the Instant Games dropdown and select Details
  2. On the Details page, find the section titled App Page and click Create New Page
  3. Go to the App Page section of the Instant Games product. Before moving on to the next step, make sure that your App Page section looks like the step on the right:

Note: If your Instant Game is not correctly associated with a page as explained above, your Game Updates will not be able to receive messaging_game_plays events.

Step 2: Activate your Game Updates via Messenger

After creating your page, you'll need to make sure to respond to its messaging webhooks. Webhooks are HTTP calls that we send to your backend when a messaging event is sent to your page. Your server's logic will then decide how to properly respond to each event, if a response is appropriate. To associate your server's endpoints with your page events, follow the instructions on the Messenger Platform Quickstart Tutorial to enable the Game Updates for your page. The table below contains information about the webhooks and permissions you will need to make your Game Updates work with Instant Games:

Section Values

Page events

messages and messaging_game_plays

Permissions

pages_messaging

Game Updates via Messenger are only permitted to use standard messaging but not pages_messaging_subscriptions. Note: do not use the GAME_EVENT message tag when sending Game Updates via Messenger as it is no longer supported.

If your Game Update via Messenger has other functionality that requires subscription messaging or customer matching you should create a separate app and apply for Messenger platform permissions again.

Step 3: Respond to messaging_game_plays webhooks

Once your Game Update via Messenger is correctly configured, your server application will start receiving messaging_game_plays webhooks every time a player closes the Instant Game. Below is an example of a server application detecting and responding to one of these webhooks.

if (event.game_play) {
  var senderId = event.sender.id; // Messenger sender id
  var playerId = event.game_play.player_id; // Instant Games player id
  var contextId = event.game_play.context_id; 
  var payload = event.game_play.payload;
  var playerWon = payload['playerWon'];
  if (playerWon) {
    sendMessage(
      senderId, 
      contextId, 
      'Congratulations on your victory!', 
      'Play Again'
    );

  } else {
    sendMessage(
      senderId, 
      contextId, 
      'Better luck next time!', 
      'Rematch!'
    );
  }
}

You can refer to the Messenger Platform documentation for more information on this webhook: Game Play Webhook Documentation.

Step 4: Bring your players back into the game

Below is an example of how to use the Graph API to send a game_play button to your players.

curl "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>" 
   -X POST 
   -H "Content-Type: application/json" 
   -d '{
  "messaging_type": "UPDATE",
  "recipient": {
    "id": "<RECIPIENT_ID>"
  },
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
        "elements": [
          {
            "title": "It has been a while since your last game. Time to get back",
            "buttons": [
              {
                "type": "game_play",
                "title": "Play Tic-Tac-Toe.",
                "payload": "{}",
                "game_metadata": {
                  "context_id": "<CONTEXT_ID>"
                }
              }
            ]
          }
        ]
      }
    }
  }
}'

You can refer to the Messenger Platform documentation for more information on this button: Game Play Button Documentation.

Step 5: Follow our guidelines and policies

Before it is launched to production, your Game Update should go through the Messenger Platform submission process. Make sure to have a look at our Game Update via Messenger Guidelines before submitting it for review, and review the developer policies to ensure your usage remains compliant.

Game Updates Quota API

To confirm the time window and number of Game Updates that can be sent to a user, you can use the game_bots_quota API.

GET graph.facebook.com/me?fields=game_bots_quota.recipient_id(<PSID>)&access_token=<page_access_token>

Response

"game_bots_quota": {
    "count": {a number indicating the remaining number of Game Updates that can be sent to a given user},
    "time_window": {a number indicating the remaining time that your game can send Game Updates to a given user},
}

More context

  1. If the user is not subscribed to Game Updates via Messenger, calling this API would return error code 551, with the message This person isn't available right now.;
  2. If there is no quota left for the user, the response would be {count: 0, time_window: 0};

References

Please refer to the documents below for more information on how to build and optimize your Game Updates via Messenger.

Next steps

Now that you know how to build an Instant Game with an associated Game Update via Messenger, it's time to test it, and prepare for launching: Testing, publishing and sharing your Instant Game