App-to-User Notifications

App-to-User (A2U) Notifications are short free-form messages you can send to players to re-engage them. They are one of the most effective ways to communicate important events, invites from friends or actions players need to take. These notifications can be used to send messages to people who have played your game.

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.

Delivery 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	Available Platforms	Example
Bot Message	Instant
Jewel	Canvas, Instant
Gaming Tab	Instant

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.

Requirements

To enable A2U notifications, your game app will require the following.

Enabled and set up for Facebook Login for Gaming
[Optional] Set up a game bot for your game to enable bot messages

This flow is supported on all game platforms: Canvas and Instant.

API Definitions

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

All of these APIs require an app or user 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.
Any required recipient userids should be an app-scoped user id. This is acquired on a successful Facebook Login for Gaming.
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. If successful, the notification id will be returned which can be used with the manage notification APIs defined further down.

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

Body Parameter	Description
`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.

Get Notification History

The notification history for a recipient can be retrieved using the following API. This will include all scheduled, sent, canceled, and failed-to-send notifications. For each of the notifications, the following fields will be returned: notification_id, status, and label (if set).

GET graph.fb.gg/{recipient_userid}/notifications

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/{recipient_userid}/cancel_all_notifications

Body Parameter	Description
`label`	If provided, will only cancel notifications with this label for the recipient

Cancel Scheduled Notification

A specific notification scheduled for a recipient can be canceled using the following API. This requires the notification id which is returned when successfully sending/scheduling a notification, or can be retrieved from the Get Notification History API endpoint.

POST graph.fb.gg/{recipient_userid}/cancel_notification

Body Parameter	Description
`notification_id`	The id of the notification to be canceled

Rate Limiting

The window to send a notification is 10 days from when a user last played your game. A maximum of up to 5 notifications can be sent to a user during this time. This limit is reset when the user plays the game again.

Scheduling a notification for a future time will not immediately be evaluated towards the above rate limit until the notification is actually sent at the designated time. However, there is a separate limit of only being allowed to schedule up to 5 pending notifications to a recipient at a time.

Notification Quota

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

With User Access Token:

GET graph.fb.gg/me?fields=notification_quota&access_token={user_access_token}

With App Access Token:

GET graph.fb.gg/{asid}?fields=notification_quota&access_token={app_access_token}

Response

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

More context

If the user’s authentication status expires, calling this API would return error code 100, with the message Unsupported get request. Object with ID {ASID} does not exist, cannot be loaded due to missing permissions, or does not support this operation;
If there is no quota left for the user, the response would be {count: 0, time_window: 0};

Best Practices

Quality of notifications is very important, as recipients on Facebook can easily turn off notifications they do not like or report them as spam. Facebook uses these signals to promote notifications people like and reduce distribution of notifications that people do not like. This helps to keep notifications useful for everyone.

People do not differentiate notifications from the rest of their experience on Facebook, so each message has a lot of power. One unwanted message can make someone start ignoring notifications or turn them off entirely.

To help you create clear and compelling notifications, we have put these best practices together:

No inactive people. Your app should not send notifications to people who have not used it in the last 28 days. Data shows that engagement among this group is significantly lower. They are also the most likely to report your notifications as spam. Apps that receive a high degree of spam reports may be disabled.
Start small. Even if you have a large app, start by testing your notifications on a few people. This way you can experiment with your notifications until you learn what works best for people.
Only send one or two notifications to people each day. After two notifications in one day, many people stop responding or mark apps as spam.
Don't fatigue your audience. It is generally not a good practice to send too many notifications to the same person within a short period of time.

Migration

If your game is already using one of the older A2U flows existing, please migrate to this API using the steps below. Each game platform follows a different legacy A2U flow, so the migration steps will differ depending on the platform your game is on.

Canvas

Since this new A2U flow uses the same Graph endpoint as the existing Canvas A2U, migration is very simple. Without making any changes, Canvas A2U notifications will continue to work as they currently do. However, to take advantage of newer features such as notification scheduling/cancellation, changes will have to be made. Here are a list of steps that should be taken:

A new message parameter must be passed in the JSON body as shown in the API Definition section above.
The old template field should be passed in the message body.
A title and image should be provided.
The old href parameter should be passed in as payload. The value will now be encoded under the payload key in the URL instead of being directly encoded.
The old ref parameter should be passed in as label.

Instant

Currently Instant Games call the Graph Page Messaging endpoint directly. To leverage A2U, call the A2U Graph API directly as documented in the API Definitions section above.

If the Instant Game is sending advanced XMA bot messages containing multiple XMA elements or buttons, then the bot_message_payload_elements parameter should be used. By providing this field, the bot message will be sent using the provided payload elements so that recipients will receive the same XMA bot message as they were previously receiving from the Graph Page Messaging endpoint.

Error Code

Error Code	Error Subcode	Response Body
613	2791031	{ error_user_msg: Only 5 notifications can be sent to a user since they last played. error_user_title: Rate Limit Reached message: Calls to this api have exceeded the rate limit. }
613	2791032	{ error_user_msg: Notifications can only be sent to players who have played within 10 days. error_user_title: Rate Limit Time Window Expiry message: Calls to this api have exceeded the rate limit. }

Error Subcode

Response Body

613

2791031

{
error_user_msg: Only 5 notifications can be sent to a user since they last played.
error_user_title: Rate Limit Reached
message: Calls to this api have exceeded the rate limit.
}

613

2791032

{
error_user_msg: Notifications can only be sent to players who have played within 10 days.
error_user_title: Rate Limit Time Window Expiry

message: Calls to this api have exceeded the rate limit.
}