Social Features: Notifications

Notifications is a common lever for acquisition, engagement and retention that we continue to support with Zero Permissions.

Note that the graph API POST endpoint supported for ZP games is functionally identical to the existing App to User Notifications graph API POST endpoint, except for two key differences: usage of App Access token (instead of user access token) and player ID (instead of App Scoped User ID).

To send notifications for Zero Permissions games, there are two main mediums

Notification Service continues to work in a similar manner.
Using App-to-User Notifications graph API with app access token, as described below.

Delivery Channels

Sending an A2U notification to a player can send notifications through the following channels: Messenger bot message, Facebook Jewel, and Facebook Gaming Tab. A messenger bot message will only be sent if your game has a Game Bot configured and the recipient player is subscribed to bot messages from your game. Otherwise, notifications will be sent through the other channels.

Below are examples of how the notifications sent through different delivery channels look like along with what game platforms each channel is available for. These were sent with the following message values:

"message": {
    "title": "Notification Title",
    "body": "This is the unified flow body",
    "media_url": "https://picsum.photos/300/300"
}

Notification Channel	Example
Bot Message
Jewel
Gaming Tab

Note: Facebook automatically performs filtering on Jewel and Gaming Tab notifications sent so that recipients are not spammed by too many notifications. This means that not all Jewel and Gaming Tab notifications will reach the intended recipient. When developing, it is recommended that you test these notifications on a new test account as these accounts have less incoming notifications so it is more likely that notifications will reach them. Bot messages will always send to the recipient if they are subscribed.

Optional to enable bot messages

Follow the steps to set up a game bot for your game to enable bot messages. Note that webhook is no longer a requirement. Only step 1 to create a page and the step to request permission for pages_messaging is required.

API Definitions

The following APIs are available through the Gaming Domain Graph API graph.fb.gg. Note the following:

The API requires an app access_token provided as a query parameter. For security, an app access token should only be acquired and used on your game servers. For more information, refer to our developer documentation.
All body parameters should be provided as JSON.
Any italicized parameters are optional.

Send/Schedule Notification

Notifications can be sent to a recipient either immediately or scheduled for a future time using the following API.

POST graph.fb.gg/{app_id}/notifications

Body Parameter	Description
`player_id`	Player ID that refers to a specific user.
`message`	Content of the message. JSON object of the format: { title: string body: string media_url: string } Please note that media_url is required for bot message if bot_message_payload_elements is null. Otherwise this will automatically be sent through other channels instead.
`label`	Label to group similar notification types together and can be used with the cancellation notification API defined below.
`payload`	Custom payload that is attached to the game URL and can be read when the user enters your game through the notification. Must be provided in JSON format.
`schedule_interval`	Time from now (in seconds) to send the notification. Must be between 300 (5 minutes) and 2592000 (30 days). Limit of 5 pending scheduled notifications per recipient.
`bot_message_payload_elements`	Optional parameter to send more advanced bot message XMAs. If specified, this will be used when sending bot messages, instead of the standard XMA created with just the message title and body. Follows message.attachment.payload.elements as defined in the public documentation here. Take the entire elements object described in the documentation and provide it under this field.

Cancel All Scheduled Notifications

All notifications scheduled for a recipient can be canceled using the following API. An optional label field can be provided to only cancel all notifications with that label for the recipient instead.

POST graph.fb.gg/{app_id}/notifications_cancel_all

Body Parameter	Description
`player_id`	Player ID that refers to a specific user.
`label`	If provided, will only cancel notifications with this label for the recipient

Frequently Asked Questions

Are the existing App to User Notifications graph APIs still supported?
- Yes, the existing APIs still work as is, but only for certain users. You might not be able to generate a user access token, but app access token should be a good substitute in most cases.
- Since all the existing APIs rely on the App Scoped User ID, you will not be able to use the existing graph APIs for users where the game cannot access their App Scoed User IDs.
- NO for new users who has onboarded to the game ONLY in Zero Permissions environment, and never before in the standard environment, the game will not have access to their associated App Scoped User IDs.
- YES for existing users where the game is able to access their App Scoped User IDs. These users have onboarded to the game in standard environment before/ during the game's migration to Zero Permissions
- Our recommendation is to migrate to the new POST endpoint API that would work for all users.