Notifications.send

From Facebook Developer Wiki

Revision as of 22:47, 28 October 2009 by Pete Bratach (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Contents

Description

Facebook will deprecate this method in late November/early December 2009 (30 days after the new email extended permission launches).

For more information, please read the Developer Roadmap.

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 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. In other words, you can send user-to-user notifications between two users provided one of the following is true:

  • User A is an application user, and is friends with User B, who is also an application user.
  • User A is an application user, and is friends with User B, who is not an application user.
  • User A is an application user, and is not friends with User B, but both are application users.

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

RequiredNameTypeDescription
required api_key string The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call.
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. If you specify the call ID in your client, you don't need to pass it with every call.
sig string An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. Facebook computes the signature for you automatically.
v string This must be set to 1.0 to use this version of the API. If you specify the version in your client, you don't need to pass it with every call.
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. You should include no more than 50 user IDs the array, otherwise you run the risk of your call timing out during processing.
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. The session key is automatically included by our PHP client. 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

$facebook->api_client->notifications_send($uid, 'some info', 'user_to_user');

Response

A comma separated list of the recipients who were successfully sent notifications.

Example Return XML

<?xml version="1.0" encoding="UTF-8"?> <notifications_send_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd">211031,1160 </notifications_send_response>

Error Codes

CodeDescription
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_user type parameter replaces the general type parameter. The app_to_user type parameter replaces the announcement type 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_send from:
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_ids to be empty, i.e. you're sending the notification to the current user.
Retrieved from "http://wiki.developers.facebook.com/index.php/Notifications.send"
reference