App-to-User Notifications

Overview

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 apps on Facebook.com, not only 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 180 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

Handling Return Values

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

{
  "success": true
}

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 follows:

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

Message Templates

Notification messages are free-form text. The Graph API enforces a maximum of 180 characters in the message field.

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 above 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-to-impression Ratio

The click-to-impression (CTI) ratio is one of the most important measure of the effectiveness of your notifications. Notifications that have a high CTI are interesting and engaging to people. Notifications with a low CTI are considered poor quality. Over time, people will tend to ignore or disable low CTI 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-to-impression (CTI) ratio. Data shows that people engage for longer when apps maintain this ratio 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.

Using ref parameters in App Analytics

In Facebook Analytics, you can track the performance of your notifications in Integrations > App Notifications. By selecting Show By Ref Parameter, you can see how different notification campaigns perform. Ref parameters are groups that can be defined by the developer when notifications are posted to the Graph API. For more information, please refer to the above section on Sending Notifications.