Session Management

After obtaining the proper authentication tokens, the first API used is the Session Management API. Applications will always use the Session Management API to login to Yahoo Messenger and obtain a session ID.

Note that the OAuth authentication token and the session ID will be used for each subsequent call to the Yahoo Messenger IM API.

Creating a Session

Creating a session is the equivalent to logging into Yahoo Messenger. A session ties requests from an authenticated Yahoo Messenger user to a particular client application that may now make requests of the Yahoo Messenger IM SDK.

There are a number of optional parameters that can be supplied to a create-session request. In the following example, the client is specifying that in addition to logging on, the Yahoo Messenger servers should also update the user’s presence state and presence message.

Here is a sample request to create a Yahoo Messenger session that does not include any parameters. Note that this request must still include an empty JSON body, which consists of an opening and closing brace {}.

Here is a common response from a create-session request.

In this case, there are five parameters that the Yahoo Messenger servers have sent back to the client. Here is a more detailed description of each.

sessionId

This is the session ID that is assigned to this login for this user and client application. This ID is required for each subsequent call to the Yahoo Messenger IM SDK. Note that in each of the following examples, we will simply replace the session ID in the example request with the word “msgrsessionid” for clarity.

primaryLoginId

This is the primary login ID that the user is logged in to Yahoo Messenger with. This attribute is important when multiple profiles have been activated as part of the login.

displayInfo

This indicates if the user has an avatar picture that is available to display. See the API documentation for more details on how to obtain avatar pictures.

server

Yahoo Messenger may assign this client a different server to make all subsequent requests. This is a load distribution strategy to keep the primary Yahoo Messenger login servers from becoming inundated with too many requests.

notifyServer

Yahoo Messenger may also assign this client a special notification server in the event that the client wishes to use long-lived HTTP GET requests (known as “Comet-style push” notifications) to receive instant notifications of other events, as opposed to using a “polling” strategy to receive events. See the Notification section for more detail.

The following API call will obtain your contact list. This is the recommended way of logging into the Yahoo Messenger APIs.

Note that we have added a URI parameter called "fieldsBuddyList" and set its value to "+groups" (the "+" is changed to %2B when URI encoded). Here is the response:

This example contains more information about each of the contacts that the user has. We'll talk more about the data this returns, including contacts, presence, and notifications shortly. However, you should note the following:

  • Performing a login to Yahoo Messenger automatically results in a login of all embedded messenger profiles (i.e., aliases).
  • Performing a login to Yahoo Messenger automatically subscribes you to the presence notifications of your contacts. Initial data is provided to the client in the form of buddyInfo notifications for only those contacts that are currently logged in.
  • Performing a login to Yahoo Messenger automatically triggers offline and system message notifications. This is provided to the client in the form of offlineMessage and sysMsg data, respectively.

Table of Contents