Yahoo Messenger IM API Definitions

Session Management

The following API calls for session management are supported. Session management is used to initiate (log in), terminate (log off) a Yahoo Messenger session, or to prevent an automatic logoff from occurring by submitting keepalive requests.

Session Management Access Server Address

<access server>/v1/session

Refer to the section "Servers" earlier to determine your access server.

Session Management API (Access Server)
HTTP Operation Functionality Input URI Input Body Response
GET Obtain the crumb associated with the Yahoo credentials. The crumb is used with the Yahoo Messenger Display Image API. Note that if your Yahoo credentials change, you must obtain a new crumb. N/A N/A

-crumb

-loggedIn

POST Create a session (login)

-fieldsBuddyList (optional)

-fieldsGroupList (optional)

-notifyServerToken (optional) [Refer to "notifyServerToken (input uri)"]

-presenceState (optional)

-presenceMessage (optional)

-clientCapabilities (optional)

Note: even though all inputs are optional, the server still expects an empty POST body (JSON: "{}")

-sessionId

-contacts (available if fieldsBuddyList was provided)

-groups (available if fieldsGroupList was provided)

-primaryLoginId

-profileLoginIds (available if profile IDs were activated by this login)

-server

-notifyServer

-displayInfo

-notifyServerToken (optional) [Refer to "notifyServerToken (response)"]

Session Management Address

<server>/v1/session

Session Management API
HTTP Definition Functionality Input URI Input Body Response
GET Validate and obtain session information.

-sid

N/A

-primaryLoginId

-profileLoginIds (optional)

DELETE Delete a session (logoff)

-sid

N/A N/A
Session Keepalive Address

<server>/v1/session/keepalive

Session Keepalive API
HTTP Operation Functionality Input URI Input Body Response
PUT

Update the active time for the user. Refrain from sending more than once every 60 minutes, or as often as the expiration of the notifyServerToken. This API will not validate the login session unless the notifyServerToken input is set to a non-zero value.

-sid

-notifyServerToken (optional) [Refer to "notifyServerToken (input uri)"]

N/A

-notifyServerToken (optional) [Refer to "notifyServerToken (response)"]

Session Management Data Type Definition
Attribute Data Type Description
sessionId string This is the Messenger session ID. The session ID is denoted by the ' sid ' attribute in subsequent API requests.
crumb string This is the Messenger crumb tied to the Yahoo credentials. The crumb is used with the Yahoo Messenger Display Image API. Note that the crumb value that is returned may not be URI safe, depending on the response content-type.
loggedIn integer

This value may be 0 or 1.

'0' indicates that the primaryLoginId is not logged into Yahoo Messenger elsewhere.

'1' indicates that the primaryLoginId is logged into Yahoo Messenger elsewhere.

primaryLoginId string The primary Yahoo ID with which the user is logged into Yahoo Messenger.
profileLoginId string The profile Yahoo ID with which the user is logged into Yahoo Messenger.
profileLoginIds list of profileLoginId(s)

This attribute is a list of profileLoginId identifiers.

Example JSON for this attribute might be:

"profileLoginIds":[{"profileLoginId":"profileID-1"}]
fieldsBuddyList multi-value

This attribute is an optimization to return subset(s) of the response "contacts" object. (See "contacts (list)" in the Schema section.)

Acceptable values are:

"+groups" (request for group data)

"+addressbook" (request for addressbook data)

"-uri" (request to remove URI data)

Cannot be used in conjunction with fieldsGroupList

fieldsGroupList multi-value

This attribute is an optimization to return subset(s) of the response "groups" object. (See "groups (list)" in the Schema section.)

Acceptable values are:

"+contacts" (request for contact list data)

"+addressbook" (request for addressbook data)

"-uri" (request to remove URI data)

Cannot be used in conjunction with fieldsBuddyList

presenceState integer

A code to indicate the current presence state. The default value is 0. A 999 value is not acceptable in this context.

For additional information, refer to the top-level section "Data Type Definition"

presenceMessage string (UTF-8) Applicable only with presenceState [0,2]. The string has a maximum of 512 bytes.
clientCapability string

Acceptable values are:

"smiley"

"buzz"

"fileXfer"

"mailAlerts"

clientCapabilities list of clientCapability(s)

This attribute is a list of clientCapability identifiers.

Example JSON for this attribute might be:

"clientCapabilities":[{"clientCapability":"buzz"}]
server string Server name to use in all subsequence requests to the APIs where <server> is indicated.
notifyServer string Server name used for the Comet Style Notification Management (see Notification Management below). This attribute corresponds to all subsequent instances of <notification server> in this document.
contacts Refer to "contacts (list)" in Schema section. This attribute is a response given as a list of contacts
notifyServerToken (input uri) string

If value equals "1", does the following:

  • Will embed an access token for the notification server using the HTTP set-cookie response.
  • The cookie value is "IM". This cookie is tied to the Yahoo credentials and must be refreshed if the credentials change.

If value equals "2", does the following:

  • Will return an access token for the notification server in the HTTP response body. See notifyServerToken (response) for more information
  • The token is tied to the yahoo credentials and must be refreshed if the credentials change
notifyServerToken (response) object

Available keys include:

"token" (string) => This is the notification server token

"expires" (integer) => This is the expiration time (in epoch seconds) of the notification server token

displayInfo map

Available keys include:

"avatarPreference" (string)

"avatarHash" (string) (optional)

"checksum" (string) (optional)

Example JSON for this attribute might be:

"displayInfo":{"avatarPreference":"2", "avatarHash":"avatar_hash", "checksum":"checksum_value"}

avatarPreference string

"0" => No display image (default)

"1" => Display image type is 'avatar'

"2" => Display image type is 'custom'

avatarHash string Checksum for the avatar display image. Used to determine if the image for the sender may already be cached locally on the client
checksum string Checksum for the custom display image. Used to determine if the image for the sender may already be cached locally on the client
Session Management Examples

Example 2.18. 

Request:

Response:


Example 2.19. 

Request:

Response:


Example 2.20. 

Request:

Response:


Example 2.21. 

Request:

Response:


Example 2.22. 

Request:

Response:


Example 2.23. 

Request:

Response:


Presence Management

The presence management APIs are used to retrieve or update the user's Yahoo Messenger presence status.

Presence Management Address

<server>/v1/presence

Presence Management API
HTTP Operation Functionality Input URI Input Body Response
GET Fetch your Yahoo Messenger status.

-sid

N/A

-presenceState

-presenceMessage (optional)

PUT Update your Yahoo Messenger status.

-sid

-presenceState

-presenceMessage (optional)

N/A
Presence Management Data Type Definition
Attribute Data Type Description
presenceState integer Refer to the top-level "Data Type Definition"
presenceMessage string (UTF-8) Applicable only with presenceState [0,2]. The string has a maximum of 512 bytes.
Presence Management Examples

Example 2.24. 

Request:

Response:


Example 2.25. 

Request:

Response:


Example 2.26. 

Request:

Response:


Contact Management

The contact and contact list management APIs are used to retrieve or update the user's Yahoo Messenger contact list.

Contact Management Address

<server>/v1/contact/{network}/{contactId}

Contact Management API
HTTP Operation Functionality Input URI Input Body Response
GET Fetch contact information for contactId.

-sid

-fields (optional)

N/A -contact (Refer to "contact" in Schema section)
Contact List Management Address

<server>/v1/contacts

Contact List Management API
HTTP Operation Functionality Input URI Input Body Response
GET Fetch collection of contact resources.

-sid

-fields (optional)

N/A -contacts (Refer to "contacts (collection)" in Schema section)
POST

Used to re-arrange contacts in the contact list.

NOTE: While this API might return a success status code, you must iterate through the individual responses in the response body to determine which request(s) succeeded and which request(s) failed.

-sid

-action=moves

-moves -moves
Contact Management Data Type Definition
Attribute Data Type Description
fields multi-value

Optimization to return subset(s) of the contact/contacts response.

Acceptable values are:

"+groups" (not currently supported with GET /contact/{network}/{contactId} )

"+clientcap"

"-uri"

"+presence"

"+addressbook"

moves array

Array of:

-buddyId [string]

-network [string] (optional - absence defaults to 'yahoo')

-fromGroup [string]

-toGroup [string]

-result [integer] (This is only applicable in the response. Refer to error definitions for a list of acceptable values (e.g., 3, 32))

Contact Management Examples

Example 2.27. 

Request:

Response:


Example 2.28. 

Request:

Response:


Example 2.29. 

Request:

Response:


Example 2.30. 

Request:

Response:


Group Management

The Group Management API calls are used to retrieve or maintain group resources for the Yahoo Messenger user, including a list of current groups, their properties, and the contacts within them.

Group Management Address

<server>/v1/group/{groupname}

Group Management API
HTTP Operation Functionality Input URI Input Body Response
GET Get group resource for {groupname}

-sid

-fields (optional)

N/A -group (refer to "group" in Schema section)
POST Rename {groupname}

-sid

-groupName N/A
Group Contact Management Address

<server>/v1/group/{groupname}/contact/{network}/{contactId}

Group Contact Management API
HTTP Operation Functionality Input URI Input Body Response
PUT Add contactId to { groupname }

-sid

-addAs (optional)

-message (optional)

NOTE: Since all inputs are optional, the server still expects an empty POST body (JSON: "{}")

N/A
DELETE Delete contactId from {groupname}

-sid

N/A N/A
Group List Management Address

<server>/v1/groups

Group List Management API
HTTP Operation Functionality Input URI Input Body Response
GET Fetch a collection of group resources

-sid

-fields (optional)

N/A -groups (Refer to "groups (collection)" in Schema section)
Group Management Data Type Definition
Attribute Data Type Description
fields multi-value

Optimization to return subset(s) of the group/groups response object.

Acceptable values are:

"+presence"

"+clientcap"

"+contacts"

"+addressbook"

groupName string (UTF-8) Max 160 bytes
addAs string Explicit profile/primary ID with which to submit the request. The default is to use the profile Yahoo ID credentials submitted.
message string Invitation message to attach to the request. The string has a maximum of 2000 bytes.
Group Management Examples

Example 2.31. 

Request:

Response:


Ignore Management

The ignore list and ignore user API calls are used to maintain a list of users that are prohibited from interacting with the Yahoo Messenger user.

Ignore List Management Address

<server>/v1/ignorelist

Ignore List Management API
HTTP Operation Functionality Input URI Input Body Response
GET Fetch the entire ignore list.

-sid

N/A -ignoredUsers (refer to "ignoredUsers (collection)" in the Schema section.)
PUT Batch insert users into the ignore list.

-sid

-members N/A
DELETE Batch delete users from the ignore list.

-sid

-members N/A
Ignore User Management Address

<server>/v1/ignorelist/{network}/{ignoreId}

Ignore User Management API
HTTP Operation Functionality Input URI Input Body Response
DELETE Delete the ignoreId from the ignore list.

-sid

N/A N/A
PUT Add the ignoreId to the ignore list.

-sid

N/A N/A
Ignore Management Data Type Definition
Attribute Data Type Description
members array

Array of:

-id => The user ID [string]

-network => IM network for the ID. [string] (optional; defaults to 'yahoo')

Example: "{"members":[ { "id":"testId","network":"yahoo" } ] }

Ignore Management Examples

Example 2.32. 

Request:

Response:


Example 2.33. 

Request:

Response:


Message Management

The following API calls for message management are supported.

Message Management Address

<server>/v1/message/{network}/{targetId}

Message Management API
HTTP Operation Functionality Input URI Input Body Response
POST Send a message

-sid

-message

-sendAs (optional)

N/A
Message Management Data Type Definition

Table 2.1. 

Attribute Data Type Description
sendAs string (UTF-8) Explicit primary/profile Yahoo ID to send the message as. The default is to use the profile Yahoo ID embedded within the Yahoo credentials
message string (UTF-8) The message string, which has a maximum of 2000 bytes.

Message Management Examples

Example 2.34. 

Request:

Response:


Notification Management

Events targeted for a login session are referred to as notifications. These include, but are not limited to, events such as instant messages and contact status updates. Clients may use either a periodic polling or comet-style push strategy to subscribe to notification events.

Basic Guidelines

As we continue to enhance our APIs, it is possible that consumers of these APIs will be exposed to notification types not documented in this section. Consumers of these APIs are expected to be able to gracefully ignore such notifications.

Notification Management (Periodic Polling) Address

<server>/v1/notifications

Notification Management (Periodic Polling) API Calls

Clients can periodically poll for pending notifications using this design. Clients are expected to poll no more than once every 5 seconds at an average or run the risk of being denied service access. Currently this technique only supports JSON-encoded response payloads.

HTTP Operation Functionality Input URI Input Body Response
GET Fetch inbound notifications for this login session.

-sid

-seq

-count (optional)

N/A

-@pendingMsg (optional)

-@syncStatus (optional)

-responses

Notification Management (Periodic Polling) Data Type Definition
Attribute Data Type Definition
seq integer The starting sequence number to fetch notifications from. The messenger counter begins at value 0.
count integer The number of notifications to retrieve, starting from the seq number. The default is 10. The minimum is 1 and the maximum is 100.
@pendingMsg integer Count of pending notifications still in the session notification cache. Absence indicates value = 0. However, this is currently not implemented.
@syncStatus integer A value of 1 indicates that certain types of unread notifications were deleted from the session notification cache owing to client idleness. On receipt of such an indicator, clients are required to refresh their contact list state by re-subscribing for presence notifications using the /subscription/presence Subscription Management API with the refresh option.
responses array List of notification(s). See "Notification Definition" below.
Notification Management (Comet-Style Push) Address

<notification server>/v1/pushchannel/{primaryLoginId}

Notification Management (Comet-Style Push) API

Clients may also maintain a long-lived HTTP GET request against the Yahoo Notification server, thereby creating the illusion of a persistent communication channel between client and server. Typical usage guidelines include:

  • Each session is restricted to having no more than one open long-lived HTTP GET request against the Yahoo Notification server.
  • After completion of a request (server response, or client timeout), clients are expected to open another long-lived HTTP GET request almost immediately.
  • Default idle timeout value is 2 minutes on the Yahoo Notification server. The server closes the long-live GET request by responding with a 200 OK. The idle timeout value can be overridden by using the 'idle' parameter in the URI.
  • Both HTTP/1.1 and HTTP/1.0 protocol requests are supported.
  • There is currently no pipeline support for HTTP/1.1
  • Clients (particularly web clients) are encouraged to submit a random value in the request URI for cache busting (e.g., &.rand=<random number>)
  • Each request must also include only ONE of the following in the request:
    • Input Cookie (IM) - This cookie value is set by the Webservice during login (POST /session), or during a session keepalive (PUT /session/keepalive) if the URI input 'notifyServerToken=1' is provided.
    • Input URI parameter (imtoken) - This value is provided by the Webservice during login (POST /session), or during a session keepalive (PUT /session/keepalive) if the URI input 'notifyServerToken=2' is provided.
HTTP Operation Functionality Input URI Input Body Response
GET Fetch inbound notifications for this login session.

-sid

-seq

-format

-idle (optional)

-imtoken (optional)

N/A

-@pendingMsg (optional)

-@syncStatus (optional)

-responses

Notification Management (Comet-Style Push) Data Type Definition
Attribute Data Type Description
idle integer Value in seconds to maintain an idle connection. If the value is greater than the supported maximum, the server will override this value with its supported maximum.
seq integer Sequence number to fetch notifications from. The messenger counter begins at value 0.
primaryLoginId string The primary login ID obtained during login (/session POST)
format string Currently, the supported formats are: "json"
@pendingMsg integer Count of pending notifications still in the session notification cache. An absence indicates value = 0. However, this is currently not implemented.
@syncStatus integer A value of 1 indicates that certain types of unread notifications were deleted from the session notification cache owing to client idleness. On receipt of such an indicator, clients are required to refresh their contact list state by re-subscribing for presence notifications using the /subscription/presence Subscription Management API with the refresh option.
responses array List of notification(s). See "Notification Definition" below.
Response HTTP Status Codes from the Notification Server

The following table lists response HTTP status codes from the notification server.

HTTP Status Code Definition
200 OK
400 Message format error; Bad URI parameters, etc.
500 Internal Yahoo server error
Non-standard HTTP Header in 200 OK Response

The following table lists any non-standard HTTP headers in a 200 OK Response from the notification server.

HTTP Header Definition
X-Max-Sequence Max sequence number of notifications at server side. This header is only set when the response Content-Length is a non-zero value.
Notification Definitions
buddyInfo

The buddyInfo message contains messenger client and login information for one or more buddies. It is received in the following scenarios.

  • When a user logs into messenger through these APIs, then one or more buddyInfo notifications are received for buddies that are not offline on the user's contact list.
  • During a login session, if a contact were to come online then a single buddyInfo notification is received.
Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
contact array (See table below) Yes

The following table provides the definition of the contact array above.

Contact Attribute Contact Attribute Data Type Contract Attribute Definition Mandatory
sender string The sender IM ID Yes
presenceState integer

Presence state information for the contact.

0 = Online

1 = Be Right Back

2 = Busy

3 = Not At Home

4 = Not At My Desk

5 = Not In The Office

6 = On The Phone

7 = On Vacation

8 = Out To Lunch

9 = Stepped Out

10 = Away

99 = Custom

999 = Idle

Yes
presenceMessage string A custom presence message for the contact No
clientType string

Enumeration of values:

"0" => Regular desktop/web client (default)

"1" => Mobile Client. Limit to 146 bytes when sending any message content

"2" => Mobile client

No
customDNDStatus integer

Applicable only under the following conditions:

1. If this value is 2 and presenceState is 99, then you can treat presenceState to be 999

2. If this value is 1 and presenceState is 99, then you can treat presenceState to be 2

3. If this value is 0 and presenceState is 99, then you can treat presenceState to be 0

No
clientCapabilities bit mask

Bit definitions:

Bit 1 (decimal value = 2) indicates if the client is capable of "smileys".

Bit 2 (decimal value = 4) indicates if the client is capable of "buzz".

Bit 15 (decimal value = 32768) indicates if the client is capable of "fileXfer".

Yes
avatarPreference string

"0" = No display image (default)

"1" = Display image type is 'avatar'

"2" = Display image type is 'custom'

No
avatarHash string A checksum for the avatar display image. This is used to determine if the image for the sender may already be cached locally on the client. No
checksum string A checksum for the custom display image. This is used to determine if the image for the sender may already be cached locally on the client. No
network string Indicates the IM network for 'sender'. The default is "yahoo". No
buddyStatus

The buddyStatus contains updated messenger presence information for a user. It is received in the following scenarios:

  • When a user whose presence has been subscribed to changes their presence information.
Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
presenceState integer

Presence state information for the contact.

0 = Online

1 = Be Right Back

2 = Busy

3 = Not At Home

4 = Not At My Desk

5 = Not In The Office

6 = On The Phone

7 = On Vacation

8 = Out To Lunch

9 = Stepped Out

10 = Away

99 = Custom

999 = Idle

Yes
presenceMessage string A custom presence message for the contact No
customDNDStatus integer

Applicable only under the following conditions:

1. If this value is 2 and presenceState is 99, then you can treat presenceState to be 999

2. If this value is 1 and presenceState is 99, then you can treat presenceState to be 2

3. If this value is 0 and presenceState is 99, then you can treat presenceState to be 0

No
clientType string

Enumeration of values:

"0" => Regular desktop/web client (default)

"1" => Mobile Client. Limit to 146 bytes when sending any message content

"2" => Mobile client

No
logOff

The logOff message is received when a user whose presence has been subscribed to goes offline.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
network string Indicates the IM network for 'buddy'. The default is "yahoo". No
status integer Currently always equal to 1. Yes
buddy string The user ID that has logged off. Yes
message

This is received when an instant message is sent to the user logged in through this API. It can also be received with a non-zero value for errorCode, which indicates a failure to deliver an IM.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
timeStamp integer Indicates when the message was sent by the sender. The value is expressed as the number of seconds since epoch (00:00:00 Jan 1, 1970) No
msg string The instant message content Yes
hash string Unique IM server generated hash. To be used for reporting SPIM abuse. No
errorCode integer

Enumeration of values:

A value of 36 indicates the IM ratio has been breached, and the receiver needs to reply before the user can send more. All other non-zero values indicate an unknown failure.

No
offlineMessage

The offlineMessage indicates messages received while the user was offline.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
messages list The list of message(s). (See Notification Definition for 'message' type.) Yes
sysMsg

This is received when a system message is sent to the user logged in through this API.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
timeStamp integer Indicates when the message was sent by the sender. The value is expressed as the number of milliseconds since epoch (00:00:00 Jan 1, 1970) No
msg string The system message content Yes
buddyAuthorize

The buddyAuthorize message is received in the following scenarios.

  • When the target of an add contact request sends back an accept or deny response.
  • When someone tries to add a user logged into messenger through these APIs.
Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
msg string The invite/accept/deny message No
authState integer

Values Enumeration:

1 = Add Response from sender

2 = Deny Response from sender

The default value is: Add Request from sender
No
fname string First name for sender No
lname string Last name for sender No
nickName string Nickname for sender No
disconnect

The disconnect message is received when a session has been expired by the server. This message is only received in the context of a Comet-style push notification scheme.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
receiver string This indicates who this notification is targeted to. Yes
reason integer

1 = Regen: This user session has been expired because of login elsewhere.

2 = Idle: This user session has been expired because of idleness.

3 = Queue Full: This user session has been expired because messages in the session notification queue are not fetched.

4 = Self-initiated Logoff: When the user does an explicit logoff.
Yes
displayImage

This message is received only when a contact changes their custom display image.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
url string The URL from where to obtain the new custom display image. Yes
checksum string A checksum for the custom image. This is used to determine if the image for the sender may already be cached locally by the client. Yes
avatarImage

This message is received only when a contact changes their avatar display image.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is 'yahoo'. No
avatarHash string Used to determine if the avatar image for the sender may already be cached locally on the client. Yes
receiver string Indicates which user this notification is targeted to. This is important when multiple profiles have been activated as part of the login. Yes
displayImagePrefs

This message is received when a contact changes their display image preferences.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
avatarPreference string

0 = No display image (default)

1 = Display image type is 'avatar'

2 = Display image type is 'custom'
No
avatarHash string Checksum for the avatar display image. This is used to determine if the image for the sender may already be cached locally on the client. No
checksum string Checksum for the custom display image. This is used to determine if the image for the sender may already be cached locally on the client. No
emailAlert

An emailAlert message is received:

  • After initial login
  • Once for each new email received during a session
  • To indicate a reset of the mail counter on the server side
Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
numEmails integer

Typically the first notification received after login indicates the number of new emails received since the user last accessed their mailbox.

During a login session, for each new email received, a notification is generated with this value set to 1.

A value of 0 indicates a reset of the mail counter on the server side. This typically occurs after the user has accessed their mailbox.

Yes

The following attribute definitions are applicable for notifications generated as a result of new emails received during a login session.

Attribute Attribute Data Type Attribute Definition Mandatory
senderName string Display name as advertised by the sender No
senderEmailAddr string Email address of the sender No
emailSubject string Subject of the email No
fileTransferInvite

The fileTransferInvite message is received by:

  • A target of a file transfer handshake to indicate an invite notification
  • A sender of a file transfer handshake to indicate an invite response
Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number. Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
sessionId string The file transfer session ID Yes
action integer

1 = Invitation Event

2 = Invitation Cancellation Event

3 = Invitation Accept Event

4 = Invitation Decline Event

Yes
fileCount integer Indicates the total file count for this invite event. This is only available when the action indicates an Invitation Event. No
fileInfo array This is only available when the action indicates an Invitation Event. (see below). No

The following table gives the definition of the "fileInfo" array.

FileInfo Attribute FileInfo Attribute Data Type FileInfo Attribute Definition Mandatory
fileSize integer Size of the file in bytes Yes
fileName string The name of the file Yes
fileTransferSend

This message is part of the file transfer handshake flow.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
sessionId string The file transfer session ID Yes
transferType integer 3 = Relay-based file transfer No
transferTag string if transferType = 3, indicates the relay server IP address to be used. No
token string if transferType = 3, indicates the relay server token to be used. This is a short-lived token. No
fileName string The file name being transferred No
errorCode integer

Indicates a failure.

Values are:

-1 = The user has cancelled the file transfer

The default value indicates an unknown failure

No
fileTransferReceive

This message is part of the file transfer handshake flow.

Attribute Attribute Data Type Attribute Definition Mandatory
sequence integer The notification sequence number Yes
sender string The sender IM ID Yes
network string Indicates the IM network for 'sender'. The default is "yahoo". No
receiver string Indicates which user this IM is targeted to. This attribute is important when multiple profiles have been activated as part of the login. Yes
sessionId string The file transfer session ID Yes
transferType integer 3 = Relay-based file transfer No
transferTag string if transferType = 3, indicates the relay server IP address to be used. No
token string if transferType = 3, indicates the relay server token to be used No
fileName string The file name being transferred No
errorCode integer

Indicates a failure.

Values are:

-1 = The user has cancelled the file transfer

The default value indicates an unknown failure

No
oneFileDone string A non-zero value indicates that one file has been successfully received and the sender can send the next file in the queue. Note that this value is a string and not an integer. No
Notification Management Examples

Example 2.35. 

Request:

Response:


Preferences Management

The Preferences Management APIs are used to set and retrieve the Yahoo Messenger user's online preferences.

Preferences Management Address

<server>/v1/preferences

Preferences Management API
HTTP Operation Functionality Input URI Input Body Response
PUT Used to bulk update preferences

-sid

-prefs N/A
GET Used to bulk fetch preferences

-sid

-cat

N/A -preferences
Preferences Management Data Type Definition
Attribute Data Type Acceptable Input
prefs array

Array of

-key

-value

-cat

Acceptable values by key:

"displayImage" : "none" , "avatar" : "custom"

Acceptable keys by category:

"general" : "displayImage"

preferences array (see 'preferences' in Schema section)
cat string Acceptable values include "general"
Preferences Management Examples

Example 2.36. 

Request:

Response:


Example 2.37. 

Request:

Response:


Buddylist Authorization Management

The Buddylist Authorization Management APIs are used to control which users are authorized to become the contact of the Yahoo Messenger user.

Buddylist Authorization Management Address

<server>/v1/buddyrequest/{network}/{adderId}

Buddylist Authorization Management API
HTTP Operation Functionality Input URI Input Body Response
DELETE Deny a contact authorization from adderId

-sid

-authReason (optional)

-authAs (optional)

NOTE: Even though all inputs are optional, the server still expects an empty JSON body. Example: "{}"
N/A
POST Accept a contact authorization from adderId

-sid

-authReason (optional)

-authAs (optional)

NOTE: Even though all inputs are optional, the server still expects an empty JSON body. Example: "{}"
N/A
Buddylist Authorization Data Type Definition
Attribute Data Type Description
authReason string (UTF-8) Reason to attach to the accept/deny response. The string has a maximum of 2000 bytes.
authAs string Explicit yahoo primary/profile ID to associate with the request. Default to Yahoo profile ID embedded within the Yahoo credentials.
Buddylist Authorization Management Examples

Example 2.38. 

Request:

Response:


Example 2.39. 

Request:

Response:


Abuse Management

The Abuse Management APIs are provided to report users that engage in unwanted behavior.

Abuse Management Address

<server>/v1/abuse/spim

Abuse Management API
HTTP Operation Functionality Input URI Input Body Response
POST Reports IM spam (SPIM). Note that reporting SPIM abuse does not automatically block the spammer. Clients may optionally use the APIs defined under Ignore List Management to block the spammer

-sid

-spammedAs (optional)

-spammerId

-initiatedBy

-network (optional)

-spims

N/A
Abuse Management Data Type Definition
Attribute Data Type Description
spammerID string The spammer IM ID
spammedAs string Explicit primary/profile Yahoo ID that was spammed. The attribute defaults to profile ID embedded within the Yahoo credentials.
initiatedBy integer

Indicates if the IM conversation was initiated by:

1 = spammee

2 = spammer

network string Indicates the IM network for 'spammerId'. The default value is "yahoo".
spim object

Object sub-elements:

-message (Original IM content)

-hash (optional) (Hash associated with IM)

-initiatedBy (1 = spammee, 2 = spammer)
spims list of spim(s) List of spim object(s). At least 1 embedded spim object must have a 'hash' value set.
Abuse Management Examples

Example 2.40. 

Request:

Response:


Subscription Management

The following describes the subscription management APIs.

Subscription Management Address

<server>/v1/subscription/presence

Subscription Management API
HTTP Operation Functionality Input URI Input Body Response
PUT Used to subscribe or re-subscribe for all presence notifications. This includes users in both the contact list and the dynamic subscription (currently not supported).

-sid

-refresh (optional)

N/A N/A
DELETE Used to unsubscribe to all presence notifications. This includes users in both the contact list and the dynamic subscription (currently not supported).

-sid

N/A N/A
Subscription Management Data Type Definition
Attribute Data Type Description
refresh integer 1 = In addition to the subscription, this flag requests the server to refresh the client's contact list view by asynchronously pushing "buddyInfo" notifications for the entire contact list.
Subscription Management Examples

Example 2.41. 

Request:

Response:


Display Image Management

See also the Yahoo Messenger Display Image Management API section below.

Image Caching
  • For avatar images, clients can use the 'avatarHash' value to determine if a locally cached avatar for a user/contact needs to be refreshed.
  • For custom images, clients can use the 'checksum' value to determine if a locally cached avatar for a user/contact needs to be refreshed.
Self Image Management

To fetch your own display image:

  • After login, use the response 'displayInfo' to determine the display image type (avatar/custom/etc). If the image is not already cached locally on the client, fetch the image from the Yahoo display image web service.

To change your display image:

  • When toggling between different image types (avatar/custom/etc), use the APIs defined under Preferences Management to update your displayImage preference.
  • If uploading a new custom image, use the Yahoo display image web service.
Contact Image Management
  • Use the data embedded within the 'buddyInfo', 'displayImage', 'avatarImage', and 'displayImagePrefs' notifications to determine the type of display image your contact uses. If the image is not already cached locally on the client, fetch the image from the Yahoo display image web service.

Stealth Management

The Stealth Management APIs are used to control which contacts may see the user as visible or invisible even when they are logged in.

Stealth Management Visible List Address

<server>/v1/stealth/visiblelist

Stealth Management Visible List API
HTTP Operation Functionality Input URI Input Body Response
PUT Used to bulk insert into the messenger visible-to-list for this session.

-sid

-members N/A
DELETE Used to bulk delete from the messenger visible-to-list only for this session. Absence of any input members will result in a delete-all operation.

-sid

-members (optional) N/A
GET Used to fetch the messenger visible-to-list.

-sid

N/A -users
Stealth Management Invisible List Address

<server>/v1/stealth/invisiblelist

Stealth Management Invisible List API
HTTP Operation Functionality Input URI Input Body Response
PUT Used to bulk insert into the messenger invisible-to-list permanently.

-sid

-members N/A
DELETE Used to bulk delete from the messenger invisible-to-list permanently. Absence of any input members will result in a delete-all operation.

-sid

-members (optional) N/A
GET Used to fetch the messenger invisible-to-list.

-sid

N/A -users
Stealth Management Data Type Definition
Attribute Data Type Description
members array

Array of:

-id (user id)

-network (optional; defaults to 'yahoo')

Example: {"members":[ [ "id":"testId", "network":"yahoo" } ] }
users collection (Refer to "users (collection)" in the Schema section.)
Stealth Management Examples

Example 2.42. 

Request:

Response:


Example 2.43. 

Request:

Response:


File Transfer Management

The File Transfer Management API is responsible for negotiating the protocol handshake to initiate file transfers between Yahoo Messenger clients. See also the Yahoo Messenger File Transfer API, listed in a later section.

Relay File Transfer Management Address

<server>/v1/filetransfer/relay

Relay File Transfer Management API
HTTP Operation Functionality Input URI Input Body Response
POST Use this for the various relay-based filetransfer protocol handshake events

-sid

-action

NOTE:See below for more information.

N/A
Protocol Flow

The relay-based file transfer handshake is a client-administered protocol. It is the responsibility of consumers of this API to ensure the protocol flow follows the guidelines provided. As an example, a client should only process file transfer send/receive notifications for invites that have been accepted by the end user.

For the sender:

  • Sender (action = invite) => Target
  • Sender can either cancel the invitation (action = cancel), or will receive a response from the target within a fileTransferInvite notification. If target declines the file transfer, or if the sender cancels the file transfer, the handshake protocol ends here.
  • For each file indicated in the invitation event:
    • Sender (action = send) => Target
    • Target will respond with a fileTransferReceive notification
    • Sender to connect to relay server on receipt of fileTransferReceive notification. Refer to the Yahoo Messenger File Transfer API documentation for more information on the relay server protocol. Be sure to use the relayIP obtained in the handshake to connect to the relay server.
    • Based on the original file transfer invite, if there is at least one (1) more file pending transfer within this file transfer session only, then:
      • The sender will wait to receive a fileTransferReceive notification with the oneFileDone value set before iterating back to the start of this loop.
      • The sender will wait to complete the existing relay based transfer before iterating back to the start of this loop.

For the target:

  • Receives a file transfer invitation event through the fileTransferInvite notification
  • Target can either accept/decline the invitation (action = accept/decline), or will receive a cancellation from the sender within a fileTransferInvite notification. If target declines the file transfer, or if the sender cancels the file transfer, the handshake protocol ends here
  • For each file indicated in the invitation event:
    • Target will receive a fileTransferSend notification indicating the file name, file transfer token, and relay server IP to connect to.
    • Target (action = receive) => Sender
    • Target to connect to relay server. Refer to the Yahoo Messenger File Transfer API documentation for more information on the relay server protocol. Be sure to use the relayIP obtained in the handshake to connect to the relay server.
    • Target (action = receive-continue) => Sender. This steps is to be performed by the target only if:
      • The file in context has completed transfer via the relay server.
      • Based on the original file transfer invite, there is at least one (1) more file pending transfer within this file transfer session.
Action Definitions

For all POST operations, use the following protocol specifications:

Action Input Body Attributes
invite

-action

-sendAs

-target

-ftSessionId

-files

cancel/accept/decline

-action

-sendAs

-target

-ftSessionId

send

-action

-sendAs

-target

-ftSessionId

-fileName

-relayIP

receive

-action

-sendAs

-target

-ftSessionId

-token

-fileName

-relayIP

receive-continue

-action

-sendAs

-ftSessionId

File Transfer Management Data Type Definition
Attribute Data Type Description
action string

Acceptable values are:

"invite"

"cancel"

"accept"

"decline"

"send"

"receive"

"receive-continue"

sendAs string The explicit primary/profile Yahoo ID to send the message as. The default is to use the primary Yahoo ID embedded within the yahoo credentials
target string The target ID
ftSessionId string The client-generated file transfer session ID. Generate any ASCII string for sharing this information between the two people engaged in the file transfer. This value is generated only by the client that initiates the invite action of the file transfer handshake and is then utilized by all subsequent actions of the handshake. This value needs to be unique across all file transfer invitations within a session. Maximum of 128 bytes.
fileName string The file name. Maximum of 1024 bytes.
relayIP string The relay server IP address. Clients need to resolve the FQDN ftrelay.messenger.yahooapis.com and use any of the IP addresses returned in the lookup as the relayIP. The relayIP is generated by the client that initiates the send action of the handshake and is passed back by the client that initiates the receive action of the handshake.
token string The token value received in the send notification
files array (max size = 10)

An array of objects that contains:

-fileName (string)

-fileSize (integer)

File Transfer Management Examples

Example 2.44. 

Request:

Response:


Example 2.45. 

Request:

Response:


Example 2.46. 

Request:

Response:


Table of Contents