From IMWiki
Revision as of 17:13, 4 April 2010 by Rekkanoryo (talk | contribs) (3. Send username, password, and challenge string to login server: Note that step 1 can also wait if challenge string is not used here)

Jump to: navigation, search


The Yahoo! Messenger Protocol is the protocol created by the Yahoo! corporation for use in its instant messaging clients. The protocol is proprietary and centralized in nature with some functionality being peer-to-peer in the newest revisions of the protocol and clients. In general, the protocol is called YMSG. Note that all YMSG packets will contain "YMSG" near the beginning of their payload.

Yahoo JAPAN also runs a second network using the same protocol. The protocol used is identical, however the servers are different and it is not possible for a user on the Yahoo JAPAN network to chat with a user on the "normal" Yahoo network (or vice versa). The Yahoo JAPAN network also appears not to be able to use all the features the other network can, for example Windows Live Messenger (MSN) interoperability.


The Yahoo protocol has the following features:

  • Avatars
  • Conferencing
  • File transfer
  • Instant messaging
  • Offline messaging
  • Voice chat
  • Webcam support
  • SMS
  • Cross-network interoperability with the Windows Live Messenger (MSN) network. This is explained below.


The Yahoo protocol connects to its servers over the following ports:

  • Chat port (Pager server): 5050 (TCP)
  • File transfer port: 80 (TCP)
  • Peer-to-peer chat: 5101 (TCP)
  • Rooms list: 80 (TCP)
  • Voice chat: 5000-5010 (UDP) or 5000-5001 (TCP)
  • Webcam: 5100 (TCP)
  • Yahoo Phone: 5055
  • Pager server request: 80 (TCP: HTTP)
  • Login server: 443 (TCP: HTTPS)

Known servers are:

  • Login server:
  • Pager server request server:
  • Pager server request server for Yahoo JAPAN:
  • Pager server hostname pool:
  • File transfer server:
  • File transfer server Japan:

Packet Structure

Add information about the packet structure here.

Login Process

Starting with Yahoo Messenger 9.0, clients use YMSG protocol version 16. The login procedure for protocol version 16 employs an HTTP request, a YMSG packet, two HTTPS requests, then a return to YMSG. The login process consists of multiple steps as follows:

1. Request a pager server address

Send an HTTP GET request for location "/capacity" to the server (or for Yahoo JAPAN). The whole URL is (or for Yahoo JAPAN).

The server responds with a message containing two lines:


The address aaa.bbb.ccc.ddd will be a real IP address usable for standard YMSG connections. It is currently in correct IPv4 format; that is, no leading zeroes are used. This is the Pager server the client should connect to.

The COLO_CAPACITY line's purpose is currently unknown, but it is believed that if the server returns COLO_CAPACITY=0 that official clients will not attempt to connect to a pager server.

2. Send YMSG packet to Pager server

Send a packet for service 57 (authentication) to the pager server. This packet must contain a single key-value pair. The key is 1 and the value is the Yahoo ID you are trying to connect with.

The server will reply with a packet for service 57 that contains 3 key-value pairs:

  • Key 1, Value Yahoo ID connecting
  • Key 13, Value 2. This key indicates the particular authentication mechanism to use. Past values are 0 and 1, but these are no longer supported.
  • Key 94, Value is a string. This string is the challenge string used during the first HTTPS request.

3. Send username, password, and challenge string to login server

Send an HTTPS GET request for location "/config/pwtoken_get?src=ymsgr&login=<username>&passwd=<password>&chal=<challengestring>" to the server (or for Yahoo JAPAN accounts). The whole URL is<username>&passwd=<password>&chal=<challengestring> (or<username>&passwd=<password>&chal=<challengestring> for Yahoo JAPAN).

Substitute the Yahoo ID for <username>, but strip from any ID sent (other domains, such as or, seem to be OK). Substitute the password for <password> and the challenge string from the previous step for <challengestring>. Note that the challenge string is not strictly required to proceed. If you choose not to use the challenge string for this request, you can wait to perform steps 1 and 2 until you've completed step 4 and are ready to start step 5.

The server will respond, but the response will vary depending on whether information supplied is correct or not.

The first line of the response's body will be an ASCII representation of an integer. This response code's values and meanings are:

Code Definition
0 Information supplied is correct.
100 Missing required field (username or password)
1013 Username contains or similar but should not; strip this information.
1212 The username or password is incorrect.
1213 The account is locked because of too many failed login attempts
1214 Security lock requiring the use of a CAPTCHA.
1218 The account has been deactivated by Yahoo
1235 The username does not exist.
1236 The account is locked due to too many login attempts (this error code means only the number of attempted logins, including both failed and successful login attempts).

If the response was 0, there will be additional lines in the response:

  • The second line of the response will start with "ymsgr=". This value is the token.
  • The third line of the response will start with "partnerid=". The purpose of this value is unknown, but seems to be somehow tied to a given username and password pair.

4. Send token to login server

Send an HTTPS GET request for location "/config/pwtoken_login?src=ymsgr&token=<token>" to the same login server used in the last step. The whole url is<token> (or<token> for Yahoo JAPAN). Substitute <token> with the token from the previous step.

Again, the server's response contains necessary information. The HTTP headers contain a B Cookie. This is not strictly needed to log in, but some clients use it.

The first line of the response will again be an ASCII representation of an integer. 0 means the information supplied to the server was correct, and 100 means there's a problem. If the first line is 0, additional lines will be present:

  • Line 2 will start with "crumb=". This is the crumb needed to calculate a hash later.
  • Line 3 will start with "Y=". This is the Y cookie and is needed later.
  • Line 4 will start with "T=". This is the T cookie and is needed later.
  • Line 5 will start with "cookievalidfor=". This is the life of the cookies in seconds. Usually this value is 86400 (1 day).

5. Calculate a hash to send to the Pager server

You now need to send a string to the Pager server. This string is calculated using the crumb and challenge string, hashed with MD5, and encoded with Yahoo's variant of Base64.

  • Concatenate the crumb and the challenge string. This is "crypt"
  • perform and MD5 hash of crypt. This is "hash"
  • Encode hash with Yahoo's Base64 variant. Some clients, like libpurple, implement their own y64 encoding function, but you can do this instead:
    • Base64-encode hash. This is "response"
    • Replace all instances of '+' in response with '.'
    • Replace all instances of '/' in response with '_'
    • Replace all instances of '=' in response with '-'

6. Send the response to the Pager server

Send a YMSG packet for service Authentication Response (0x54) with the following key-value pairs:

Key Value
1 Yahoo ID
0 Yahoo ID
277 Y cookie
278 T cookie
307 "response" calculated in previous step
244 Client build ID. More on this below.
2 Yahoo ID
2 1
59 B cookie
98 Chat locale
135 Client version. More on this below.


  1. All three places using the Yahoo ID must use the same ID string that was used to obtain the token and crumb. If a domain had to be stripped to obtain the token and crumb, that stripped version of the username must be used here as well.
  2. The B cookie isn't strictly needed for login, but will make clients less distinguishable from the official client.
  3. The key 244 and final key 2 values are numbers, but are treated as ASCII characters instead of as integers.
  4. The meaning of key 98's value is an assumption. The US official client puts "us" in this value; the JAPAN official client puts "jp". This value is not strictly needed for login, but will make clients less distinguishable from the official client.

Client Versions

The official clients have two different version numbers. One is the version number a user sees in the "About Yahoo! Messenger" box. The other is completely hidden from the user and used only during the login process. We'll call these versions the version and build ID, respectively. Each version has precisely one build ID associated with it. Known pairs are listed:

Client version and build ID pairs
Client Version Build ID Network Supported 4194239 Normal Yes 4186047 Japan Yes

Useful Links