Frequently Asked Questions

How Do Mail Alerts Work?

To enable mailAlerts, you require the following:

  • At login time, you must provide the 'mailAlerts' value as a clientCapability.

Once mail alerts are enabled:

  • Typically right after login, clients will receive a single emailAlert notification through the notification management channel indicating the count of new emails received since the user last accessed their mailbox.
  • Thereafter, clients will receive a single emailAlert notification through the notification management channel for each new email received.
  • Notifications are also generated when the mail counter is reset on the server side.

How To Fake HTTP PUT/DELETE Requests

Where applicable, our APIs have been extended to allow clients to fake HTTP PUT/DELETE requests by using the following:

  • Submit the request as documented for the PUT/DELETE request, but use the HTTP POST method
  • Submit an additional URI parameter (&_method) to indicate the real HTTP method being requested

The following table provides examples for DELETE and PUT.

API Alternative API
DELETE /v1/session POST /v1/session?_method=delete
PUT /v1/presence POST /v1/presence?_method=put

How To Retrieve a Contact List

The Yahoo Messenger team recommends using the following strategy:

  • Obtain the raw contact list as a response from the login request to the Session Management API (e.g., using the fieldsBuddyList '+groups' options, as in POST /v1/session?fieldsBuddyList=%2Bgroups&fieldsBuddyList=%2Baddressbook)
  • Since a login automatically subscribes you to the presence of the contacts on your contact list, initial presence and client capability information is pushed to the client in the form of 'buddyInfo' notifications for contacts that are currently not offline.
  • Thereafter, any incremental information about your contacts is also pushed to the client through various notifications (e.g., buddyInfo, buddyStatus, logoff, avatarImage, displayImage, etc). Please review the appropriate notification definitions under the Notification Management section for more information.

Understanding the Contact Add and Authorization Process

Protocol Flow for the Adder

  1. The adder will first initiate an add request using the Group List Management API (e.g., PUT /v1/group/{groupname}/contact/{network}/{addeeId}). The Yahoo Messenger team recommends that the Adder associate addressbook data for the Addee at this time.
  2. If the Addee accepts the request, the following notifications are received by the Adder in any order.
    • A 'buddyAuthorize' notification is received by the Adder with the authState indicating the acceptance.
    • A 'buddyInfo' notification is sent to the Adder for the newly added Addee.
  3. If the Addee rejects the request, a 'buddyAuthorize' notification is received by the Adder with the authState indicating the rejection.

Protocol Flow for the Addee

  1. A 'buddyAuthorize' notification is received by the Addee with the authState indicating an add request from the Adder.
  2. The Addee can then choose to accept or deny this request by using the APIs provided in the Buddylist Authorization Management section. If the request is ignored, the add request will be generated again by the Yahoo Messenger servers when the Addee next logs in.

Normalizing IDs in the Yahoo network

The Messenger protocol requires clients to understand when IDs in the "yahoo" network may require some client side normalization. When submitting a request to an API that involves an action against a contact, messenger clients are required to strip out the domain portion of the contact identifier using the following rule:

  • If the contact exists within the "yahoo" network, then strip out any "@yahoo.*" input except if the domain value is "@yahoo.cn". For example, "id@yahoo.com.sg" should be submitted to the API as 'id'. While "id@ymail.com" should be submitted to the API as "id@ymail.com"

Some APIs that this rule is applicable against:

  • GET /v1/contact/{network}/{contactId} => The value for {contactId}may require client side normalization
  • PUT /v1/contact/{network}/{contactId} => The value for {contactId}may require client side normalization
  • PUT /v1/group/{groupname}/contact/{network}/{contactId} => The value for {contactId}may require client side normalization
  • DELETE /v1/group/{groupname}/contact/{network}/{contactId} => The value for {contactId}may require client side normalization
  • POST /v1/message/{network}/{targetId} => The value for {targetId}may require client side normalization
  • DELETE /v1/buddyrequest/{network}/{adderId} => The value for {adderId}may require client side normalization
  • POST /v1/buddyrequest/{network}/{adderId} => The value for {adderId}may require client side normalization

Other places that this rule is applicable against:

  • The value for 'sendAs'in any API that lets you set the Yahoo ID sender
  • The value for 'receiver'or 'target'in any API that lets you set a Yahoo recipient
  • The value for the attribute 'id'in the 'members' array in the following APIs:
    • /v1/ignorelist
    • /v1/stealth/visiblelist
    • /v1/stealth/invisiblelist

Table of Contents