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
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
The Yahoo protocol has the following features:
Cross-network interoperability with the Windows Live Messenger (MSN) network.
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)
* Voice chat: 5000-5010 (UDP) or 5000-5001 (TCP)
* Pager server request: 80 (TCP: HTTP)
* Login server: 443 (TCP: HTTPS)
* Login server: login.yahoo.com
* Pager server request server: vcs1.msg.yahoo.com
* Pager server request server for Yahoo JAPAN: cs1.msg.vip.ogk.yahoo.co.jp
* Pager server hostname pool: scsa.msg.yahoo.com
* File transfer server: filetransfer.msg.yahoo.com
* File transfer server Japan: filetransfer.msg.yahoo.co.jp
Add information about the packet structure here.
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
vcs1.msg.yahoo.com (or cs1.msg.vip.ogk.yahoo.co.jp for Yahoo JAPAN). The whole
URL is http://vcs1.msg.yahoo.com/capacity
(or http://cs1.msg.vip.ogk.yahoo.co.jp/capacity for Yahoo JAPAN).
The server responds with a message containing two lines:
CS_IP_ADDRESS=aaa.bbb.ccc.ddd 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
* 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
### 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 login.yahoo.com (or login.yahoo.co.jp for Yahoo JAPAN accounts).
https://login.yahoo.com/config/pwtoken_get?src=ymsgr&login=<username>&passwd=<password>&chal=<challengestring>
https://login.yahoo.co.jp/config/pwtoken_get?src=ymsgr&login=<username>&passwd=<password>&chal=<challengestring>
Substitute the Yahoo ID for <username>, but strip
@yahoo.com from any ID sent
(other domains, such as sbcglobal.net or rocketmail.com, 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:
0 | Information supplied is correct.
100 | Missing required field (username or password)
1013 | Username contains
@yahoo.com 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
* 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
### 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
https://login.yahoo.com/config/pwtoken_login?src=ymsgr&token=<token> (or
https://login.yahoo.co.jp/config/pwtoken_login?src=ymsgr&token=<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 in the format "Set-Cookie: B=<cookie>".
This is not strictly needed to log in, but some clients (including the official
client) use it. If you choose to use it, ignore the characters "B=", but take
the remainder of the text up to (but not including) the first semicolon.
The first line of the response's body 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
* Line 2 will start with "crumb=". This is the crumb needed to calculate a hash
* 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
* 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:
307 | "response" calculated in previous step
244 | Client build ID. More on this below.
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
1. The B cookie isn't strictly needed for login, but will make clients less
distinguishable from the official client.
1. The key 244 and final key 2 values are numbers, but are treated as ASCII
characters instead of as integers.
1. 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 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
-------------- | -------- | ------- | ---------
9.0.0.2162 | 4194239 | Normal | Yes
9.0.0.1727 | 4186047 | Japan | Yes
* [
Wikipedia Article](
http://en.wikipedia.org/wiki/Yahoo!_Messenger)
* [
Some basic descriptions of the Yahoo protocol](
http://www.venkydude.com/articles/yahoo.htm)
* [
Yahoo Messenger Protocol v 9](
http://libyahoo2.sourceforge.net/ymsg-9.txt)
