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 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.
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.
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.
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.
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.
Yahoo! Messenger may also assign this client a special notification server in the event that the client wishes to use long-lived
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:
buddyInfonotifications for only those contacts that are currently logged in.