App-to-User Notifications

This feature is no longer available for new submissions. This documentation is intended solely for developers with existing games.

App-to-User Notifications are short free-form messages you can send to people using your app to reengage them. They are one of the most effective ways to communicate important events, invites from friends or actions people need to take. You use these notifications to send messages to people who have authorized your app.

App-to-User Notifications are available to all Facebook Web Games. The notifications are only surfaced on the desktop web version of Facebook. Apps can send notifications to people who have authorised the app. No special or extended permission is required.

When a notification is delivered, it lights the notifications jewel on Facebook and appears in the drop down. Notifications appear with the app icon to the left, interspersed with other notifications based on chronological sorting.

Notifications themselves are short — up to 120 characters — strings of custom text. You can reference people by their FB app-scoped IDs. These will be expanded to show people's actual names, but the names won't be clickable. See the message template section below for more details.

When people click the notification, they'll be taken to a URL you specify with the notification.

Implementation

Sending notifications

Apps can generate notifications by issuing a HTTP POST request to the /user_id/notifications Graph API, with an app access_token. You may find more details by referring to the Graph API notifications edge.

POST /{recipient_userid}/notifications?access_token=... &template=...&href=...

Parameters

Parameter	Description
`href`	The relative path or GET params of the target (for example, `index.html?gift_id=123`, or `?gift_id=123`). This will be used to construct an absolute target URL based on your app settings. The logic is that, on web, if the setting exists for games on Facebook.com, the target URL will comprise Game App URL + `href`. If not, the notification will not be shown. The absolute URL will include some special tracking params (`fb_source`, `notif_id`, `notif_t`) to the target URL for developers to track at their side.
`template`	The customised text of the notification. See the message template section below for more details.
`ref`	Separate your notifications into groups so they can be tracked independently in App Analytics.

Handling Return Values

If the call is successful, the Graph API gives the following response:

{
  "success": true
}

Note: When we predict a low chance of the recipient to interact with the notification the notification might not be shown to the recipient even though the Graph API call was successful.

If not, the Graph API response will include an error with a corresponding exception message.

If the user you're trying to send to has not authenticated your app, you will get a response like the following:

{
   "error": {
      "message": "(#200) Cannot send notifications to a user who has not installed the app",
      "type": "OAuthException",
      "code": 200
   }
}

If a person you're trying to tag has not authenticated your app, you will get the following response:

{
   "error": {
      "message": "(#200) Cannot tag users who have not installed the app",
      "type": "OAuthException",
      "code": 200
   }
}

If your template text contains more than 180 characters, the API will return an error as below. Take note that anything more than 120 characters will be truncated.

{
   "error": {
      "message": "(#100) template parameter cannot be longer than 180 characters.",
      "type": "OAuthException",
      "code": 100
   }
}

Note: If people turn off notifications from your app, posting will still succeed but the notification will just not appear in the UI.

Message Templates

Notification messages are free-form text. The Graph API accepts a maximum of 180 characters in the message field, and will truncate messages after 120 characters.

Plain Text Messages

This notification can be generated with the following graph API call:

POST /{recipient_userid}/notifications?
     access_token=...& 
     href=...& 
     template=You have people waiting to play with you, play now!

Personalized Message Templates

You use @[USER_ID] to include user_ids, which will be replace with the person's full name and highlight it at rendering time.

The notification above can be generated by formatting the template with the user IDs as shown in the code below.

POST /{recipient_userid}/notifications?
     access_token=...& 
     href=...& 
     template=@[596824621] started a game with you, play now!

Similarly, the notification below also uses the @[USER_ID] syntax but has more than one actor (person) in the template.

POST /{recipient_userid}/notifications?
     access_token=...& 
     href=...& 
     template=@[596824621] and @[10149999096285761] started a game with you!

The Graph API verifies each USER_ID to make sure it is valid Facebook user and has already authenticated your app. If any are invalid, the API call will fail.

Tracking Performance

Minimum Click-Through Rate

The click-through-rate (CTR) is one of the most important measure of the effectiveness of your notifications. Notifications that have a high CTR are interesting and engaging to people. Notifications with a low CTR are considered poor quality. Over time, people will tend to ignore or disable low CTR notifications, hurting performance of your app's performance and others, too.

To ensure the notifications channel remains interesting to people on Facebook, apps that send more than 50,000 notifications in a week are required to maintain at least a 17% weekly click-through-rate (CTR). Data shows that people engage for longer when apps maintain this rate or higher. Apps that do not maintain this rate on a weekly basis may be temporarily disabled.

Most applications can maintain this rate quite easily if they follow the simple best practices in the section below.

Manual Optimisation

Localization of Message Template

To send non-English notification, developers need to manually track the locale of person. After the person has logged in, the locale can be accessed via the Graph API edge /{user-id}?fields=locale. For games on Facebook.com, the locale information can be retrieved from the HTTP post request. With knowledge of the locale, developers can manually create message templates that corresponds to the user's locale.

Send timing

Developers can better optimise the notifications to be sent in the person's waking hours. After the person has logged in, the timezone can be accessed via the Graph API edge /{user-id}?fields=timezone. With timezone information and using ref parameters, developers can better target and optimise for the best timing to send notifications to people.

Auto-Targeting (Beta)

Auto-Targeting enables you to send App-to-User Notifications while taking advantage of Facebook's enhanced targeting. Enabling Auto-Targeting frees you from maintaining a high click-through-rate (CTR) of 17% yourself, as Facebook will automatically deliver notifications to the people who are most likely to engage with your app.

With this feature enabled, you can target larger audience segments with your notifications and Facebook will automatically deliver notifications to the people who are most likely to engage with your app. For example, we have identified that notifications more than a few days old generally have poor performance - hence we will deliver less of those. Most developers who have turned on Auto-Targeting and increased notification sends have seen large increases in engagement with App-to-User Notifications.

To take advantage of Auto-Targeting, you may turn it on in the Settings tab of the App Dashboard Settings.

Note that for applications that have not used App-to-User Notifications in the past and have recently implemented it, you will be automatically opted in to Auto-Targeting.

Best Practices

Since quality is so important, recipients on Facebook can easily turn off notifications they don't like or report them as spam. We use these signals to promote notifications people like and reduce distribution for notifications people don't like. This helps to keep notifications useful for everyone.

People don’t 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’ve 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 so you stay below the 50,000-per-week threshold. 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 good practice to send too many notifications to the same person within a short period of time. By using App Analytics, developers can find the sweet spot to re-engage players by comparing results using ref parameters of different timings - 2 hours, 6 hours, 1 day, 3 days, 1 week or even up to 2 weeks.
Auto-Targeting. If you are sending more than 50,000 notifications a week and struggling to maintain the 17% CTR, you should turn on Auto-Targeting to let Facebook automatically deliver notifications to the people who are most likely to engage with your app.