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
  1. The Yahoo user Joe installs the Zynga game Farmville on the Yahoo Homepage.
  2. Joe invites Yahoo user Jane to play Farmville.
  3. An invite and a notification are sent to Jane.
  4. Jane sees the notification and clicks Accept.
  5. 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
  1. Yahoo user Joe comments on Yahoo user Jane's update.
  2. A notification is sent to Jane that includes Joe's comment.
User Ignores a Notification
  1. Yahoo user Joe uses a notification to send a gift to Yahoo user Jane.
  2. Jane sees the notification and clicks Ignore.
  3. The notification is removed from Jane's list of notifications.
User Accepts a Gift
  1. Yahoo user Joe uses a notification to send a gift to Yahoo user Jane.
  2. Jane sees the gift and accepts it.
  3. The notification is removed from Jane's list of notifications.
User Deletes Notification
  1. Yahoo user Mary, from an application, sends a notification to Yahoo user Joe.
  2. Joe deletes the notification without taking action.
  3. The notification is removed from Joe's list of notifications.
User Jane Blocks User Joe in Application Foo
  1. Yahoo user Joe sends a gift notification from the application Foo to Yahoo user Jane.
  2. Jane sees notification and clicks Block Joe When Using App Foo.
  3. All notifications from Joe in Foo are hidden in a queue.
  4. Joe tries to send Jane a notification the next day from application Foo.
  5. Joe receives no error.
  6. The notification is checked against Jane's blocked list and is put into a hidden state.
  7. Jane signs into Yahoo and sees no notifications from application Foo.
  8. 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.

https://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

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": "https://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": "https://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

XML Syntax for Notifications Object

Example JSON Response Body for GET Notifications

Example XML Response Body for GET Notifications

Table of Contents