Send notifications to authenticated app users using Facebook API
Monday, September 2, 2013
App notifications is one of the most effective ways to re-engage app users by sending them a free-form message to take an action, notify about an event or to invite friends. Please note that app notifications can only be sent to users who have authorized the app. Please take additional steps to make sure that the user is authorized if necessary.
Notification can contain text which contain up to 180 characters and once delivered, it will be displayed in the notification area of the user. Simple plain text or templates can be sent as notifications. For example, You can specify any other authorized users UID in the notification, which when sent, the UID will be expanded to show people's actual names, but they won't be clickable. The click through URL of a notification can be set while sending the notification.
Sending notification using API
Apps can send a notification to a user by the issuing an HTTP POST request to the /USER_ID/notifications Graph API, with an app access token. The format for sending an API notification is as follows.
POST /{recipient_userid}/notifications?access_token= … &template= … &href= …href - Facebook only supports canvas application to send notifications(But there is a work around for page tab applications by specifying the canvas URL and redirecting the window.top location to Page tab URL).href is the relative path of the canvas application (for example, "index.html?gift_id=123", or "?gift_id=123"). Then Facebook will construct proper target URL based on your app settings. The logic is that, on web, if Canvas setting exists, Facebook always show “Canvas URL + href”. If not, it show nothing. In the future (not in this version), we will also use existing URL re-writing logic to support mobile canvas and native mobile apps. Facebook also appends some special tracking params (fb_source, notif_id, notif_t) to the target URL for developers to track where the traffic is coming from.
One example of target URL displayed in the jewel is:
https://apps.facebook.com/appnamespace/?fb_source=notification¬if_id=notif_514699839_145756436&ref=notif¬if_t=app_notification
template - The customized text for notification
ref - you can group notifications by using ref parameter and can view reports of these groups in Insights
Templates can be
- Plain text (eg - POST /{recipient_userid}/notifications?access_token= … & href= … & template=Your notification text )
- Light weight template -You can refer user_ids in the notification text and the userids will be rendered as users' full name while displaying. The user_ids should be of valid Facebook users and users who have already authorized your app, else Facebook will throw an error. (Eg - POST /{recipient_userid}/notifications?access_token= … &href= … &template=@[596824621] and @[657682378] started a game with you, play now!)
{
"success": true
}- If the user you're trying to send to has not authenticated your app, you will get an error 200:"message": "(#200) Cannot send notifications to a user who has not installed the app"
- If a person you're trying to tag has not authenticated your app, you will get an error 200: "message": "(#200) Cannot tag users who have not installed the app"
- If your template text contains more than 180 characters, we throw an error 100: "message": "(#100) template parameter cannot be longer than 180 characters."
Obtaining App Access token
App access token can be obtained by issuing an HTTP GET request to the following GRAPH API
https://graph.facebook.com/oauth/access_token?client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&grant_type=client_credentials
and you will get the result which contains the app access token as follows access_token=YOUR_APP_ACCESS_TOKEN. You can save this access token and can be reused until it is refreshed manually by the developer. (You can refresh the app access token from your app settings page in developers.facebook.com)
For detailed documentation, Please refer
