Facebook instant games can have a Messenger Platform Bot attached. Although this is optional, it gives your game a powerful channel for re-engagement. Here's how to create and set up your Game Bot:
To create a Game bot, 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:
To create a page with these criteria, visit your App Dashboard and follow these steps:
![]() | ![]() |
Note: If your Instant Game is not correctly associated with a page as explained above, your bot will not be able to receive messaging_game_plays
events.
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 bot for your page. The table below contains information about the webhooks and permissions you will need to make your bot work with Instant Games:
Section | Values |
---|---|
Page events |
|
Permissions |
|
Instant Games bots are only permitted to use standard messaging but not pages_messaging_subscriptions
. Note: do not use the GAME_EVENT
message tag when sending bot messages as it is not supported anymore.
If your bot has other functionality that requires subscription messaging or customer matching you should create a separate app and apply for Messenger platform permissions again.
messaging_game_plays
webhooksOnce your bot 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.
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.
Before it is launched to production, your game bot should go through Messenger Platform submission process. Make sure to have a look at our Bot Checklist before submitting it for review.
Please refer to the documents below for more information on how to build and optimize your Game bot.
Now that you know how to build an Instant Game with an associated Game bot, it's time to test it, and prepare for launching: Testing, publishing and sharing your Instant Game