Yahoo! Messenger

Prev — Schema

Frequently Asked Questions — Next

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

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)"]

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

-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

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

GET

Validate and obtain session information.

-sid

N/A

-primaryLoginId

-profileLoginIds (optional)

DELETE

Delete a session (logoff)

-sid

N/A

Session Keepalive Address

<server>/v1/session/keepalive

Session Keepalive API

HTTP Operation Functionality Input URI Input Body Response

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)"]

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:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 245
{
   "sessionId" : "msgrsessionid",
   "primaryLoginId" : "myPrimaryYahooId",
   "profileLoginIds": [
      { "profileLoginId": "myProfileYahooID-1" },
      { "profileLoginId": "myProfileYahooID-2" },
   ],
   "server" : "rcore1.messenger.yahooapis.com",
   "notifyServer" : "rproxy1.messenger.yahooapis.com",
   "contacts" : [
      {
         "contact" : {
            "id" : "buddyID1",
            "groups" : [
               {
                  "name" : "Friends"
               },
               {
                  "name" : "Family"
               }
            ],
            "uri" : "rcore1.messenger.yahooapis.com/contact/yahoo/buddyID1"
         }
      },
      {
         "contact" : {
            "id" : "buddyID2",
            "groups" : [
               {
                  "name" : "Family"
               }
            ],
            "uri" : "rcore1.messenger.yahooapis.com/contact/yahoo/buddyID2"
         }
      }
   ],
   "displayInfo" : {
      "avatarPreference" : "1",
      "avatarHash" : "avatar_hash",
      "checksum" : "checksum_value"
   }
}

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

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

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

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)

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

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`

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

Contact Management Data Type Definition

Attribute Data Type Description

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))

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

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

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

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

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

Group List Management Address

<server>/v1/groups

Group List Management API

HTTP Operation Functionality Input URI Input Body Response

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)

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:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 245
{
   "groups" : [
      {
         "group" : {
            "uri" : "rcore1.messenger.yahooapis.com/group/Friends",
            "name" : "Friends",
            "contacts" : [
               {
                  "contact" : {
                     "uri" : "rcore1.messenger.yahooapis.com/contact/yahoo/buddyID1",
                     "id" : "buddyID1",
                     "addressbook" : {
                        "id" : "10",
                        "nickname" : "buddy id 1",
                        "lastModified" : 1304629969
                     },
                     "presence" : {
                        "presenceState" : 2,
                        "clientType" : "mobile"
                     }
                  }
               },
               {
                  "contact" : {
                     "uri" : "rcore1.messenger.yahooapis.com/contact/yahoo/buddyID2",
                     "id" : "buddyID2",
                     "addressbook" : {
                        "id" : "11",
                        "nickname" : "buddy id 2",
                        "lastModified" : 1304629969
                     },
                     "presence" : {
                        "presenceState" : 0,
                        "clientType" : "pc"
                     }
                  }
               }
            ],
         },
      }
      {
         "group" : {
            "uri" : "rcore1.messenger.yahooapis.com/group/Family",
            "name" : "Family",
            "contacts" : [
               {
                  "contact" : {
                     "uri" : "rcore1.messenger.yahooapis.com/contact/yahoo/buddyID2",
                     "id" : "buddyID2",
                     "presence" : {
                        "presenceState" : 0,
                        "clientType" : "pc"
                     }
                  }
               }
            ]
         }
      }    
   ],
   "start" : 0,
   "total" : 2,
   "count" : 2
}

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

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" } ] }`

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

HTTP Operation	Functionality	Input URI	Input Body	Response
`POST`	Send a message	`-sid`	`-message` `-sendAs` (optional)	N/A

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

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`

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

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`

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

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`

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

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`"

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

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

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

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

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

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

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

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

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:

Prev — Schema

Frequently Asked Questions — Next