My Apps Sign in

Chapter 2. Yahoo Messenger IM API

Getting Started

The following sections will help you to get familiar with the Yahoo Messenger IM API.

Basic Guidelines

Here are the basic guidelines for using the Yahoo Messenger IM API:

  1. All APIs require Yahoo credentials.
  2. All APIs require a session ID input, except when submitting a request to generate a session ID (e.g., login).
  3. All APIs can potentially return a 4xx or 5xx HTTP status code with an optional embedded error element.

Yahoo Credentials

The Yahoo Messenger IM API accepts standard OAuth credentials passed through the HTTP Authorization header. The API also allows usage of the PLAINTEXT OAuth signature method when submitting credentials.

Servers

The following servers are available:

  • Production: developer.messenger.yahooapis.com

Supported Content Types

The following content types are supported:

  • application/json;charset=utf-8

Data Type Definition

The following table lists the standard attribute data type definitions used throughout the Yahoo Messenger IM API.

Attribute Data Type Definition
sid string The session identifier
presenceState integer

The current presence state.

Acceptable values are:

-1 = Offline

0 = Online

2 = Busy

999 = Idle

network string

Acceptable values are:

"yahoo"

Error Definitions

This following table lists the error definitions for the Yahoo Messenger IM SDK.

Application Error Codes Application Error Code Definitions
0 OK
1 Internal Server Error
2 User Exists Error
3 User Does Not Exist Error
4 Invalid Credentials Error
6 Max Buddies Error
7 Max Groups Error
8 Group Exists Error
10 Max Ignored Users Error
12 User Is Contact Error
22 Yahoo Parents Control Error
28 Session Expired Error
30 Ban Error
32 Invalid Group ID Error
33 User in Ignore List Error
42 Max Pending Contact Authorizations Error
-1000 Invalid Sender Error
-1001 Invalid Target Error
-1003 Unsupported Content Type Error
-1004 Unsupported User Agent ID Error
-1005 Invalid Arguments / Bad Message Error
-1006 Underage Error
-1009 Capability Check Error
(default) Internal Server Error

The following table lists the possible error codes for each HTTP status.

HTTP Status Application Error Codes
200, 201 N/A
400 -1005, -1004, -1003, -1001, -1000, 2, 3, 6, 7, 8, 10, 12, 32, 33, 42
401 4, 28
403 -1009, -1006, 22, 30
404 3, 32
500 1, All Other Error Codes

User Agents

The following user agents are supported.

Mobile Clients

The following format is supported for mobile clients.

Please note the following:

  • The Application Version should be a 4-part string, such as 1.0.0.1

Here is a sample user agent for mobile clients.

The string is allowed in the following HTTP header:

  • User-Agent
Other Clients

The following format is supported for other clients. Although the format is shown on several lines, it should appear entirely on a single line.

Please note the following:

  • The Application Version should be a 4-part string, such as 1.0.0.1

Here is a sample user agent for other clients. Again, note that the entry should appear on a single line.

The string is allowed in the following HTTP header:

  • User-Agent
  • X-Yahoo-Msgr-User-Agent

Sample Session

The following steps are typically executed in a Yahoo Messenger session:

  1. Contact the Yahoo authentication server to obtain Yahoo OAuth credentials.
  2. Submit the Yahoo OAuth credentials obtained in the previous step to login to Yahoo Messenger using "POST /session". Note that:
    • 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 buddies. Initial data is provided to the client in the form of buddyInfo notifications for only those buddies 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.
  3. Submit the Yahoo OAuth credentials and session ID obtained in the previous steps to the various APIs supported.
  4. Eventually, submit the Yahoo OAuth credentials and session ID obtained to "DELETE /session" to logout from Yahoo Messenger.

Table of Contents