Notifications

Description

Use this URI to get a list of a user's notifications or send the user a notification. Notifications have daily limits and can be blocked by the receiver.

Use Cases

The use cases below outline several common scenarios where notifications would be sent to users.

User Installs an Application and Invites Friends

The Yahoo! user Joe installs the Zynga game Farmville on the Yahoo! Homepage.
Joe invites Yahoo! user Jane to play Farmville.
An invite and a notification are sent to Jane.
Jane sees the notification and clicks Accept.
Later Jane gets an email notification. She clicks Accept and is told the invitation has already been accepted.

User Adds a Personal Note to Notification

Yahoo! user Joe comments on Yahoo! user Jane's update.
A notification is sent to Jane that includes Joe's comment.

User Ignores a Notification

Yahoo! user Joe uses a notification to send a gift to Yahoo! user Jane.
Jane sees the notification and clicks Ignore.
The notification is removed from Jane's list of notifications.

User Accepts a Gift

Yahoo! user Joe uses a notification to send a gift to Yahoo! user Jane.
Jane sees the gift and accepts it.
The notification is removed from Jane's list of notifications.

User Deletes Notification

Yahoo! user Mary, from an application, sends a notification to Yahoo! user Joe.
Joe deletes the notification without taking action.
The notification is removed from Joe's list of notifications.

User Jane Blocks User Joe in Application Foo

Yahoo! user Joe sends a gift notification from the application Foo to Yahoo! user Jane.
Jane sees notification and clicks Block Joe When Using App Foo.
All notifications from Joe in Foo are hidden in a queue.
Joe tries to send Jane a notification the next day from application Foo.
Joe receives no error.
The notification is checked against Jane's blocked list and is put into a hidden state.
Jane signs into Yahoo! and sees no notifications from application Foo.
Jane unblocks the Foo user Joe and will now see all of Joe's future notifications from Foo.

URI

GET returns the notifications received by the user identified by {guid}. POST creates a new notification for the user identified by {guid}. After posting notifications, the notification ID is in the returned response, and the GUID of the sender is in the Authorization header.

http://social.yahooapis.com/v1/user/{guid}/received_notifications

Filters

Filters can only be used when calling the HTTP GET method of the Notifications URI.

If you call GET without a filter, you get a response including all of the user's notifications. Search filters allow you to get a subset of the authenticated user's notifications. For example, you can use a search filter to get only those notifications that are pending in the returned response.

Display filtering allows you to select specific information for each returned notification. For example, you can use a display filter to return Notification Objects that only contain the appid, appmsg, and appurl elements in the returned response. Search and display filtering can be used independently or together.

Filters use criteria that include two components: a predefined set of keys and user-defined values.

The keys are case-sensitive, and the values for search filters have the following constraints:

Cannot contain commas, question marks, or forward slashes.
Cannot begin with a pound sign, an equal sign, a semicolon, or an angle bracket.
Cannot be a single exclamation mark.

Search Filtering

Using search filters, you can get Notification Objects in the response that match certain criteria.

Syntax

To request notifications by the category, state, or sender, use the following syntax:

/v1/user/{guid}/received_notifications;{field_name}={field_value}

The table below lists the allowed values for {field_name}.

Field Name	Allowed Values	Syntax Example	Description
`category`	A string representing a category of notifications.	`/v1/user/received_notifications;cageory=games`	Returns the notifications that were grouped under the specified category.
`sender`	A user's GUID. For example: `UQIDWJNWVNQD4GXZ5NGMZUSTZZ`	`/v1/user/received_notifications;sender=UQIDWJNWVNQD4GXZ5NGMZUSTZZ`	Returns the notifications sent by user identified by the GUID.
`since`	Date in RFC 3339 format. For example: `2010-04-12T23:20:50.52Z`	`/v1/user/received_notifications;since=2010-04-12T23:20:50.52Z`	Returns the notifications returned since the specified date.
`state`	`PENDING`, `DEFERRED`, `COMPLETED`	`/v1/user/received_notifications;state=PENDING`	Returns the notifications in the specified state. The following are the allowed states: `pending`, `deferredcompleted`

Search Filter Examples

This example returns the pending notifications for the user identified by {guid}.

/v1/user/{guid}/received_notifications;state=PENDING

The following example returns the notifications categorized as friends for the user identified by {guid}.

/v1/user/{guid}/received_notifications;category=friends

Display Filtering

Display filters are used with the HTTP GET method to obtain a subset of the fields for each returned Notification Object in the response.

Syntax

Display filters are appended to the URI for the Notifications API. The GUID of the user who received notifications is represented by {guid} and {field1}, {field2}, and {field3} are the only fields of each Notification Object in the returned response.

/v1/user/{guid}/received_notifications;fields={filed1,field2,..}

Display Filter Examples

This example returns Notification Objects that only contain the appid, appmsg, and appurl elements for the user identified by {guid}.

/v1/user/{guid}/received_notifications;fields=appid,appmsg,appurl

This example returns the Notification Objects containing only the recipient, sender, and sendmsg elements for the notification receiver identified by {guid}.

/v1/user/{guid}/received_notifications;fields=recipient,sender,sendmsg

HTTP Operations Supported

GET
POST

Query Parameters Supported

count
format
start
view

The view parameter can be given the values below.

tinyusercard - returns the Tinyusercard of the sender of each notification and can be used with .imgsize and .imgssl to return the image data of the senders.

Matrix Parameters Supported

category
count
fields
sender
since
sort
state
start

Scopes Required

GET: Read/Write Yahoo! Updates
POST: Read/Write Yahoo! Updates

URL Templates

The value for the urltemplate element is a URL containing variables that are assigned values when a user takes an action based on the choices given in a notification. For example, a notification could give the user the choices to click Accept or Ignore, and the user's action could be to click Accept.

The following example URL for the urltemplate element has the variables {choice}, {id}, and {sender_guid}.

"urltemplate": "http://apps.yahoo.com/farmville?choice={choice}&id={id}&sender_guid={sender_guid}"

When the user takes an action on the notification, such as clicking Accept, the variables are substituted with values as seen here:

"urltemplate": "http://apps.yahoo.com/farmville?choice=accepted&id=23412345&sender_guid=RM3RSV73F4DJF4ZN3DVLJPK5F4

The list below gives a brief description of the variables in the URL value for the urltemplate element:

{choice} - The notification receiver's action based on the given selections, such as accepted, rejected, and pending.
{sender_guid} - The GUID of the sender of the notification.
{id} - The unique ID of the notification.
{receiver_guid} - The GUID of the receiver of the notification.

Note

The base domain specified by urltemplate should match the base domain of the application URL provided when the application was registered.

Elements of the Notifications Object

Element	JSON Data Type	XML Schema Type	Description
`start`	number	nonNegativeInteger	The index of the first notification.
`total`	number	nonNegativeInteger	The number of notifications returned.
`count`	number	nonNegativeInteger	The total number of notifications.
`notification`	array of Notification Objects	zero or more Notification Objects	Contains the details for each notification.

Elements of the Notification Object

Element	JSON Data Type	XML Schema Type	Required for Write?	Read Only?	Description
`appid`	string	string	No	Yes	The ID of the application that created the notification.
`appmsg`	string	string	Yes	No	The message that was sent with the notification.
`appname`	string	string	No	Yes	The name of the application that created the notification.
`appurl`	string	anyURI	No	Yes	The URL to the application.
`category`	string	string	No	No	A label used to group notifications. For example: `friends`, `coworkers`, `games`.
`choices`	array of Choice Objects	zero of more Choice Objects	Yes	No	The choices of actions given to the notification receiver and the URL template that updates the notification.
`created`	string	dateTime	No	Yes	The time that the notification was created.
`expiry`	string	nonNegativeInteger	No	No	The expiration date of the notification in POSIX time.
`favicon`	string	anyURI	No	Yes	The URL to the favicon associated with the source that created the notification.
`id`	string	string	No	Yes	A unique ID assigned to a notification when the notification is created.
`image`	Image Object	Image Object	No	No	The size and URL to an image associated with the notification.
`new`	boolean	boolean	No	Yes (POST), No (PUT)	Indicates whether the notification has been seen by the user. The default value is `true` for new notifications. The value can be changed to `false` by calling `PUT` on the Notification URI.
`recipient`	string	string	No	Yes	The GUID of the notification receiver.
`sender`	string	string	No	Yes	The GUID of the notification sender.
`sendmsg`	boolean	boolean	No	No	Indicates whether a message gets sent with the notification. The default value is "true".
`state`	string	enumeration	No	Yes (POST), No (PUT)	The state of the notification. The default value is `PENDING` for new notifications. The value can be changed to by calling `PUT` on the Notification URI.The following are the allowed values: `PENDING`, `DEFERRED`, `COMPLETED`
`title`	string	string	Yes	No	The title of the notification.
`type`	string	string	Yes	No	The type of notification. The only allowed value is "nfsimple".
`updated`	string	dateTime	No	Yes	The time of the last update action taken on a notification.
`uri`	string	anyURI	No	Yes	The URL to the notification.
`usrmsg`	string	string	No	No	The message that a user writes and sends with the notification.

Elements of the Choice Object

Element	JSON Data Type	XML Schema Type	Description
`label`	string	string	The choice of action given to the notification receiver. For example: `Accept`, `Deny`, `Ignore`
`urltemplate`	string	anyURI	The URL containing variables that are assigned values when a notification is acted upon (update operation). See URL Templates for more information.

JSON Syntax for the Notifications Object

{
  "notifications" : 
  {
    "start" : number,
    "count" : number,
    "total" : number,
    // Array of notification Objects
    "notification" : 
    [
      {
        "id": "string",        // Notification ID
        "appid" : "string",    // ID of the application 
                               // that created notification
        "state": "string", 
        "created": "string",   // Timestamp in seconds
                               // RFC 3339 date format;   
        "updated": "string",   // Timestamp in seconds 
                               // RFC 3339 date format; 
        "recipient": "string", // GUID of target/receiver user
        "sender": "string",    // GUID of sender
        "appname": "string",   // Commercial name of app
        "favicon": "string",   // Favicon url
        "appurl": "string",    // URL of app
        "title": "string",     // Title shown to user
        "type": "string",      // Denotes notification type.                                                                                           // The only allowed value 
                             // is "nfsimple".
        "appmsg": "string",  // App-defined message (required)
        "category": "string", // Category specific to
                              // the app that can be used
                              // for filtering.
        "usrmsg": "string",   // User-defined message 
                              // (optional)
        "image": 
        {
          "size": "string",   // In the format "WxH"
          "width": number,
          "height": number,
          "imageUrl": "string" // URL to image
        },
        "sendmsg": boolean, // Deliver message via 
                            // email to receiver
        "expiry": "string", // Time in seconds
                            // RFC 3339 date format
        "choice": "string", // Selected choice. The value
                            // of the "id" element
                            // in the Choice Objects.
                            // Empty when the state 
                            // is pending.
        "choices": 
        [
          {
            "label": "string", 
            "urltemplate": "string"  // URL template
          }, 
          {
            "label":"string", 
            "urltemplate": "string"
          },
          {
            "label":"string", 
            "urltemplate" : "string"
          } 
        ]  
        "uri" : "string"     // URI of this 
                             // Notification Object        
      },
      ...
    ] 
  }
}

XML Syntax for Notifications Object

Example JSON Response Body for GET Notifications

{
  "notifications": 
  {
    "total": 14,
    "count": 14,
    "start": 0, 
    "notification":
    [
      {
        "choices":
        [
          {
            "urltemplate": "http://apps.yahoo.com/farmville?choice={choice}&id={id}&sender_guid={sender_guid}",
            "label": "&Accept" 
          },
          {
            "urltemplate": "http://apps.yahoo.com/farmville?choice={choice}&id={id}&sender_guid={sender_guid}",
            "label": "Deny"
          },
          {
            "urltemplate": "http://apps.yahoo.com/farmville?choice={choice}&id={id}&sender_guid={sender_guid}",
            "label": "Ignore"
          }
        ],
        "state": "PENDING",
        "image":
        {
          "height": 48, 
          "imageUrl": "http://ext.yimg.com/ec?url=http%3a%2f%2fimages.bbgsite.com%2fnews%2f2010%2f02%2f06%2ffarmville-farm.gif&t=1287469115&ttl=604800&sig=5MBddG_n7tqdpul_rMVmqQ--~B",
          "width": 48,
          "size": "48x48"
        },
        "appid": "-yossd3e",
        "appurl": "http://www.yahoo.com",
        "sendmsg": true,
        "type": "nfsimple",
        "uri": "/v1/notification/du4a8re25modk7j8j790o00o40pda",
        "recipient": "BF23MDCSGGOWS6BVC5FB6V2WW4",
        "expiry": "2011-01-19T06:14:07Z",
        "id": "du4a8re25modk7j8j790o00o40pda",
        "sender": "BYOFJYRJSHXWPWE63YUGN5LM2I",
        "appmsg": "Have your own online farm!",
        "category": "beginner",
        "new": true,
        "title": "Farmville",
        "created": "2010-10-19T06:18:35Z",
        "updated": "2010-10-19T06:18:35Z",
        "favicon": "http://l.yimg.com/a/i/us/soc/updts/si1_avatars.gif",
        "appname": "Zynga Farmville",
        "usrmsg": "Earn points by taking care of your farm."
      },
      ...
    ]
  }
}

Example XML Response Body for GET Notifications

<notifications xmlns="http://social.yahooapis.com/v1/schema.rng" xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:start="0" yahoo:count="14" yahoo:total="14">
  <notification>
    <uri>/v1/notification/du4a8re25modk7j8j790o00o40pda</uri>
    <id>du4a8re25modk7j8j790o00o40pda</id>
    <new>true</new>
    <state>PENDING</state>
    <created>2010-10-19T06:18:35Z</created>
    <updated>2010-10-19T06:18:35Z</updated>
    <recipient>BF23MDCSGGOWS6BVC5FB6V2WW4</recipient>
    <sender>BYOFJYRJSHXWPWE63YUGN5LM2I</sender>
    <appid>-yossd3e</appid>
    <appname>Zynga Farmville</appname>
    <favicon>http://l.yimg.com/a/i/us/soc/updts/si1_avatars.gif</favicon>
    <appurl>http://www.yahoo.com</appurl>
    <title>Farmville</title>
    <type>nfsimple</type>
    <appmsg>Have your own online farm!</appmsg>
    <category>beginner</category>
    <usrmsg>Earn points by taking care of your farm.</usrmsg>
    <image>
      <size>48x48</size>
      <width>48</width>
      <height>48</height>
      <imageUrl>http://ext.yimg.com/ec?url=http%3a%2f%2fimages.bbgsite.com%2fnews%2f2010%2f02%2f06%2ffarmville-farm.gif&t=1287469115&ttl=604800&sig=5MBddG_n7tqdpul_rMVmqQ--~B</imageUrl>
    </image>
    <expiry>2011-01-19T06:14:07Z</expiry>
    <choices>
      <label>Accept</label>
      <urltemplate>http://apps.yahoo.com/farmville?choice={choice}&id={id}&sender_guid={sender_guid}</urltemplate>
    </choices>
    <choices>
    <sendmsg>true</sendmsg>
  </notification>
</notifications>

Yahoo! Developer Network

Notifications

Description

Use Cases

User Installs an Application and Invites Friends

User Adds a Personal Note to Notification

User Ignores a Notification

User Accepts a Gift

User Deletes Notification

User Jane Blocks User Joe in Application Foo

URI

Filters

Search Filtering

Syntax

Search Filter Examples

Display Filtering

Syntax

Display Filter Examples

HTTP Operations Supported

Query Parameters Supported

Matrix Parameters Supported

Scopes Required

URL Templates

Note

Elements of the Notifications Object

Elements of the Notification Object

Elements of the Choice Object

JSON Syntax for the Notifications Object

XML Syntax for Notifications Object

Example JSON Response Body for GET Notifications

Example XML Response Body for GET Notifications

Table of Contents