Receiving Messages

Retrieving an incoming message that has been sent to the client user requires the Notification Management API. Currently, there are two strategies for obtaining notifications:

  1. Poll the Yahoo Messenger IM SDK server at regular intervals (e.g., every 10 seconds), essentially asking the question, “Do you have anything new for me?”
  2. Send a long-lived HTTP GET request to the server, and wait for a reply that may come seconds, minutes, or even hours later. When a reply is received, it means that the Yahoo Messenger IM SDK servers have one or more new notifications for the client. After the reply is received, or the request times out, the client will immediately send another long-lived HTTP GET request to the server, and repeat the process. This is known as a “Comet-Style Push” notification strategy, and requests made in this style must use the server identified by the “notifyServer” field presented when the user first obtained a session ID.

Here is an example of getting a message that was sent to the client user from another contact using the polling mechanism.

Note the additional parameters on the URL request: the sequence number, represented by “seq”. There are two parameters that go into a notification request.

seq

This is the starting notification sequence number. A sequence number is, in effect, an ID number assigned to each notification that persists as long as the user maintains the login session. Note that the Yahoo Messenger IM SDK may continue to relay the same notification until the notification expires and is removed from the server system. Once a client handles a notification with a specific sequence number, it may safely ignore that notification sequence number for the remainder of login session. As such, you can use this parameter to request notifications from the next unhandled sequence number. This is a required parameter.

count

This parameter is an optional integer that indicates the number of new notification messages the client wishes to receive, starting with the sequence number. The default value is 10, but it can range anywhere from 1 to 100.

Here is an example reply that may come back from the Yahoo Messenger servers, indicating that there is a notification with sequence number 5.

Let’s look at the three main response parameters in more detail.

@pendingMsg

This parameter is an integer count of the pending notifications still in the session notification cache. If there are no pending messages, the value shown is 0. Note that this value is not currently implemented.

@syncStatus

A Boolean value, either 0 (false) or 1 (true). If the value is 1, it indicates that certain types of unread notifications were deleted from the session notification cache owing to client idleness. See the Notification Management API for more information.

responses

This is a list of notifications for the client.

There are a wide variety of notifications that can be sent to the client. However, for simplicity, we’ll focus on the “message” notification. This notification can be broken down into five simple parameters.

sequence

This is the notification sequence number.

sender

This is the sender’s contact ID.

receiver

This parameter indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login.

msg

This is the String-based instant message.

hash

Unique IM server generated hash. This is useful for reporting spam IM (SPIM) information. See the Abuse Management API for more information.

Table of Contents