The Yahoo Messenger team recommends obtaining the client list directly from the session management API. Since a login automatically subscribes you to the presence of the contacts on your contact list, initial presence and client capability information is pushed to the client in the form of buddyInfo notifications for contacts that are currently not offline. Thereafter, any incremental information about the user’s contacts is also pushed to the client through various notifications (see the various notification definitions in the Notifications API section) during the login session. However, this flow assumes that clients are able to maintain state for the contact list during a login session on the client side.

If, however, you are creating an application that does not maintain the contact list, you can obtain it using the following call. (Note that you can obtain the same information by using the Group Management API, which will return similar information except as a list of groups instead of a list of contacts.)

Here is an example response from the Yahoo Messenger IM SDK for a user that contains two contact “friends.”

This response consists of a collection of contacts, as defined in the Schema (Contact Collection). Note that this response contains the complete list of contacts that belongs to the user. However, there are times that the response may only be a subset of contacts, depending on any optional parameters that were sent with the request.

The response shown above contains the following parameters.


This is a listing (a JSON array) of contact elements.


This integer tells where in the contact list this response starts. This is useful in the event that the listing returned is a subset of the complete contact list for this user. If the response consists of the entire list, this value will always be ‘0’.


This integer tells how many contact elements have been returned in this response. If the response consists of the entire contact list, this number will always match the total.


This number tells how many total contacts the user has.

Now let’s look at each contact element. Each entry consists of two elements.


This is the ID of the contact. By default, since the network element is missing, the network of the ID is implied to be "yahoo" as per the Contact schema definition.


This is the URI used with the Yahoo Messenger IM SDK obtain more information on the contact.

The Contact URI

Note that the URI associated with a contact can be broken down into three areas: the server address, the IM network, and the contact ID. For example, consider the following contact ID:

Here, the server address for contacts is:

The network is:


And finally, the contact ID is:


At present, the only supported network is “yahoo”. However, as other IM network are integrated into the Yahoo Messenger IM SDK family, this value will change.

Table of Contents