Notifications.send
From Facebook Developer Wiki
Contents |
Description
Sends a notification to a set of users. Notifications are items sent by an application to a user's notifications page in response to some sort of user activity within an application. You can also send messages to the logged-in user's notifications (located both on the right hand side of the chat bar, as well as on their notifications page.
Your application can send a number of notifications to a user in a day based on a number of metrics (or buckets). To get this number, use admin.getAllocation or check the Allocations tab on the Insights dashboard for your application in the Facebook Developer application. If the number of recipients exceeds the allocation limit, then the notification gets sent to the first n recipients specified in to_ids (see the Parameters table below), where n is the allocation limit.
Notifications sent to the notifications page for non-application users are subject to spam control. Read more information about how spamminess is measured. Additionally, any notification that you send on behalf of a user appears with that user's notifications as a "sent notification."
There are two types of notifications: user-to-user and application-to-user notifications. A user-to-user notification is sent on behalf of one user to one or more other users and requires the sending user's active session (with the same allocation amounts as today).
Application-to-user Notifications
Application-to-user notifications are sent on an application's behalf and do not require an active session. The allocation for these is also available through admin.getAllocation.
User-to-user Notifications
User-to-user notifications can be sent to application users who aren't friends of the application user generating the notification. User-to-user notifications can be sent from an application user to the friends of the user, whether or not they use the application.
User-to-user notifications appear in real time, as popup alerts. These alerts appear above the notifications icon on the chat bar at the bottom of the Facebook window. These notifications briefly appear in the notifications list afterward, so the user can still see it some time after the notification arrives.
The user on whose behalf you are sending the notification also gets an alert when the notification gets sent, and that user can choose to not send it.
For the user's perspective on this feature, read the Facebook company blog. You can read more about how notifications should be used.
Requests Vs. Notifications
Note: Requests are actions initiated by the user (such as invitations to install an application or play a game) and appear on other users' request pages. You generate requests using fb:request-form.
Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. | |
|---|---|---|---|---|
| call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. | ||
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| to_ids | array | Comma-separated list of recipient IDs. These must be either friends of the logged-in user or people who have added your application. To send a notification to the current logged-in user without a name prepended to the message, set to_ids to the empty string. | ||
| notification | string | The content of the notification. The notification uses a stripped down version of FBML and HTML, allowing only text and links (see the list of allowed tags). The notification can contain up to 2,000 characters. | ||
| optional | session_key | string | The session key of the logged in user. An active session is required only if you are sending a user-to-user notification. | |
| format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | ||
| callback | string | Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter. | ||
| type | string | Specify whether the notification is a user_to_user one or an app_to_user. (Default value is user_to_user.) |
Example Queries
Response
A comma separated list of the recipients who were successfully sent notifications.
Example Return XML
Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 4 | The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed. | |
| 5 | The request came from a remote address not allowed by this application. | |
| 100 | One of the parameters specified was missing or invalid. | |
| 101 | The API key submitted is not associated with any known application. | |
| 102 | The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key. | |
| 103 | The submitted call_id was not greater than the previous call_id for this session. | |
| 104 | Incorrect signature. |
Notes
- The
user_to_usertype parameter replaces thegeneraltype parameter. Theapp_to_usertype parameter replaces theannouncementtype parameter. - If you are using an older version of facebookapi_php5_restlib.php or facebookapi_php4_restlib.php, then change line 256 (line 258 for PHP 4) in
notifications_sendfrom:
- 256: array('to_ids' => $to_ids, 'markup' => $markup, 'no_email' => $no_email));
- to:
- 256: array('to_ids' => $to_ids, 'notification' => $markup));
- This is needed to send the notification. Otherwise the script always returns Invalid Paramater.
- The user name of the logged-in user is prepended to the notification. Your notification FBML should take this into account by starting with a verb. This does not happen if you set
to_idsto be empty, i.e. you're sending the notification to the current user.
See Also
You can see a real world example of this method in the Footprints demo application. Go to Demos for more details and to download and install the demo apps.
