The first step in an MSN Messenger session is logging into a notification server. If you have previously stored the IP address of a notification server, you can connect directly to that. Otherwise, you must connect to the "dispatch server". The official client uses messenger.hotmail.com, port 1863 as the dispatch server for direct and SOCKS-based connections, and gateway.messenger.hotmail.com, port 80 as the dispatch server for HTTP connections. If you want to connect to a third-party MSN Messenger network, you should use a different dispatch server.

If you cannot connect to a previously stored notification server, try the dispatch server instead. If you cannot connect to the dispatch server, either you are having connection problems, or the MSN Messenger network is down (which happens from time to time).

When you first connect to a notification server, you are in the "login stage", which involves agreeing on a protocol version to use, authenticating yourself to the MSN server, and possibly being redirected to another notification server if the current one is overloaded.

During the login stage, the server behaves differently to normal. Communication is essentially synchronous - the client sends a command to the server, the server responds, the client sends another command, and so on. If you send a command at the wrong time (for example, if you send a VER command when the protocol version to use has already been negotiated), the server will send a 715 error, then disconnect you. If you send a command which has no meaning during the login stage (for example, a SYN command), you will be disconnected immediately with no error. None of these rules apply outside of the login stage.

VER

The VER command specifies which versions of the MSN Messenger protocol are supported. The VER command has a TrID and a list of supported protocol versions as parameters (note that protocol versions are case sensitive). The server's response will be a VER command with the same TrID. If the server supports at least one of these protocols the parameters will be a list of the supported protocol(s), otherwise the response will contain a single parameter of 0, and will disconnect you immediately (this shouldn't normally happen).

The first parameter in the list (not including CVR0) is the protocol version you should use in this session. In principle, CVR0 can occur anywhere in the list, but in practice it's only ever been observed at the end of the list. In version 8 of the MSN messenger protocol, you must support at least "MSNP8" and "CVR0".

Below are some examples:

<o> Connect: messenger.hotmail.com 1863

>>> VER 0 MSNP8 CVR0\r\n

<<< VER 0 MSNP8 CVR0\r\n

<o> Continue Session . . .

<o> Connect: messenger.hotmail.com 1863

>>> VER 0 MSNP8 MYPROTOCOL CVR0 \r\n

<<< VER 0 CVR0 MSNP8\r\n

<o> Continue Session . . .

<o> Connect: messenger.hotmail.com 1863

>>> VER 0 MYPROTOCOL\r\n

<<< VER 0 0\r\n

<o> Server Closes Connection

<o> Connect: messenger.hotmail.com 1863

>>> VER MSNP8 CVR0\r\n (No TrID)

<o> Server Closes Connection

CVR

The CVR command sends version information about a client and operating system to the server. For the official client, the server will reply with information about the version of the client that users are currently recommended to use (which may be the same as the version currently being used).

The CVR command includes information about the language you speak, the name and version of your client, and the name and version of your OS. You can send a CVR command to the NS at any time after you have finished logging in, but the official client always sends it immediately after sending the initial CHG. You can send CVR as many or as few times as you like. CVR has a TrID and 8 parameters.

The first parameter is hexadecimal number specifying your locale ID (e.g. "0x0409" For U.S. English).
The second parameter is your OS type (e.g. "win" for Windows).
The third parameter is your OS version (e.g. "4.10" for Windows 98).
The fourth parameter is the architecture of your computer (e.g. "i386" for Intel-comaptible PCs of type 386 or above).
The fifth parameter is your client name (e.g. "MSMSGR" for the official MSN Messenger client).
The sixth parameter is your client version (e.g. "6.0.0602").
The seventh parameter is always "MSMSGS" in the official client. Your guess about what this means is as good as mine.
The eighth parameter is your passport.

Like with any other command, the server will reply to a CVR command with a CVR reply. For some reason, though, the official client would be just as happy if you replaced CVR with CVQ in the reply. The reply command will contain 5 parameters:

The first parameter is a recommended version of the client for you to use, or "1.0.0000" if your client information is not recognised.
The second parameter is identical to the first.
The third parameter is the minimum version of the client it's safe for you to use, or the current version if your client information is not recognised..
The fourth parameter is a URL you can download the recommended version of the client from.
The fifth parameter is a URL the user can go to to get more information about the client.

If your current client version is less than the minimum safe version, that means there is some serious vulnerability in your version of the client. The official client will immediately disconnect if this is the case, though the server doesn't mind. Here is the CVR information sent by version 6.0.0602 of the official client.

>>> CVR 2 0x0409 win 4.10 i386 MSNMSGR 5.0.0544 MSMSGS example@passport.com\r\n

<<< CVR 2 6.0.0602 6.0.0602 1.0.0000 http://download.microsoft.com/download/8/a/4/8a42bcae-f533-4468-b871-d2bc8dd32e9e/SETUP9x.EXE http://messenger.msn.com\r\n

Initial USR

After receiving the response to CVR, you must send the USR command. It has a TrID.

The first parameter is the authentication system (always TWN).
The second parameter is always the letter I (standing for initiating authentication).
The third parameter is the account name that you want to log on with.

If the server does not like your USR, it will close the connection with no reply, or possibly send an error first, Error 911 is sent if you replace the I with an S or when sending invalid account names such as hotmail.com. Error 928 is sent if you send a bad ticket.

Sometimes, when the server is having problems or is down for maintenance, it will reply with an error instead of logging you in. Some possible errors include error 500, error 601, error 910, and error 921.

Otherwise, the server will either respond with a XFR (transferring you to another notification server) or a subsequent USR.

XFR

messenger.hotmail.com always sends XFR, but gateway.messenger.hotmail.com never does. Microsoft's other notification servers very rarely send XFR - presumably, they send it when they are overloaded or going down for maintenance.

The XFR command will have the same TrID as the previous USR and four parameters.

The first parameter is NS, telling you that it is transferring you to a notification server.
The second parameter is the IP and port of the notification server, separated by a colon. The port seems to always be 1863, but it's best not to rely on that always being the case.
The third parameter is always 0 (zero).
The fourth parameter is the IP address and port (separated by a colon) of the server that you are currently connected to.

Below is an example USR command and XFR reply.

>>> USR 2 TWN I example@passport.com\r\n

<<< XFR 2 NS 207.46.106.145:1863 0 207.46.104.20:1863\r\n

After you receive the XFR, the server will close the connection. You must connect to the specified notification server and start the login process again. There is no communication between notification servers, so you could specify a different protocol version, name and so on when logging into the new notification server.

Subsequent USR response

The subsequent USR response has three parameters: TWN, an S for subsequent instead of an I, and a very long string used in TWN authentication. This string is so long that including it on this page would cause horizontal scrolling, making the page harder to read. Please see the authentication example page for an example.

TWN Authentication

TWN ("Tweener") authentication is the way MSN Messenger plugs into Microsoft's Passport Authentication framework. Passport authentication is Microsoft's attempt to provide a "single sign-on" system for all Internet services, from Messenger to on-line banking. Some background information about it is available on MSDN. Understanding Tweener doesn't require any background knowledge of Passport, but you will need a basic understanding of the HyperText Transfer Protocol version 1.0 or 1.1.

Tweener authentication involves the following steps:

The client stores the string sent in the USR response.
The client (optionally) connects to the Passport "Nexus", and retrieves the URL of a login server. This result doesn't change very often, so it can be cached.
Using the stored string, passport, and password, the client authenticates itself with this login server. The server will do one of:
- Redirect the client to another login server for the client to authenticate with (note: this server must not be cached).
- Report a failure in the login process, with an appropriate error message.
- Return a "ticket". This ticket is sent back to the notification server in the USR reply.

Authentication with MS Passport involves sending HTTPS requests to Microsoft's Passport servers in order to retrieve a passport "ticket", which is then sent to the server you really want to connect to. HTTPS is HyperText Transfer Protocol encrypted using "Secure Sockets Layer". It is recommended that you find a library for your chosen programming language that supports HTTPS - even if you choose to write your own HTTP parser, you should not try to implement SSL (it's far too complex and security-sensitive to implement as part of a larger project). Some HTTPS libraries are listed on the projects page. Passport servers allow you to either send your login details as an HTML file in the body of the request or as headers of the HTTPS request itself. The "HTML" method is only intended for use by web browsers, but will work fine for MSN Messenger clients. The "header" method is recommended for Messenger clients, and is the only method explained on this site.

Connecting to the Nexus involves sending an HTTPS GET request for the URL "https://nexus.passport.com/rdr/pprdr.asp". The server should always reply with a 200 OK message with an empty body. The important information is contained in the "PassportURLs" header, which contains a comma-separated list. The "DALogin" field of this header contains the address of the login server. This value isn't technically a valid URL, so your HTTPS library might require you to add "https://" to the start of it.

The client should then send an HTTPS GET request for the URL given to it by the Nexus. The request should include an "Authorization" header. The value of this header is one long string with no spaces, made up of the string "Passport1.4 OrgVerb=GET,OrgURL=http%3A%2F%2Fmessenger%2Emsn%2Ecom,sign-in="), your URL-encoded passport, ",pwd=", your URL-encoded password, ",", and the challenge string given to you by the Notification Server.

The server's response should be either a 200 OK message (for success), 302 Found (for redirection) or 401 Unauthorized (for failure). The message will contain either an "Authentication-Info" or a "WWW-Authenticate" header. It's not known why two different header names are used, although at present "WWW-Authenticate" is only used with failed logins. It's safest to assume that the two header names are interchangeable. The header's value will begin with " Passport1.4 ", then a comma-separated list of fields of the form "key=value". The first field will have a key "da-status" and a value of "success", "failed" or "redir" (redirect).

If the response is a failure, the header will include a "cbtxt" field with a URL-encoded error message, and a "cburl" field that contains the URL of a picture you might want to display along with it.

If the response is a redirection, there will be a separate "Location" header, which includes the URL of the login server which the client is being redirected to. At the time of writing, the client will only be redirected if it has a passport that ends in "@hotmail.com" or "@msn.com". The client must begin the login step again.

If the response is a success, the header will include a "from-PP" field, which contains the ticket to return to the Notification Server. This field has a slightly unusual format, in that the value is inside apostrophes and includes several equals signs (but no commas).

Final USR command

After getting your ticket, you must send the final USR command. It has a TrID, the first parameter is TWN, the second parameter is S, and the third parameter is your ticket.

If the ticket is correct, the server will respond with a USR with OK as the first parameter, your account name as the second parameter, your URL-encoded display name as the third parameter, 0 or 1 as the fourth parameter, and 0 as the fifth. The fourth parameter represents whether or not your Passport has been verified (1 is true, 0 is false). We don't yet know what the fifth parameter means.

If your your ticket is incorrect, the server will respond with error 911 and close the connection. If anything else is wrong (including an invalid digest size), the server will close the connection with no error.

Example Session

Some of the lines sent as part of the authentication process are so long that including them on this page would cause horizontal scrolling, making the page harder to read. Please see the authentication example page.

What Next?

You are now successfully logged in, and can set your initial presence, as shown in the Presence page. You should also sync your lists soon after you are logged in. You will probably also receive one or more messages (MSG) from the NS after receiving the final USR as explained in the DS/NS Messages page.

Maximising Efficiency

To make things go as quickly as possible when logging in, you can send multiple commands at once without waiting for response (for some reason, I have problems when putting them in the same packet). Send VER and USR together to the DS. Only specify the one protocol version you intend to use, and send a@b.c to messenger.hotmail.com as your email address. Don't bother with the INF. You may also substitute \ns for \r\ns to save bandwidth.

Logging Off

To log off of the NS (and have MSN send your offline status to everyone), the easiest way is to just close the socket. If you do not properly tear down your connection (e.g. if you're on a modem and are disconnected), you will still appear to be on-line and unresponsive for several minutes.

The proper way to log off is by sending the OUT command to the NS with no parameter and no TrID. The server will immediately close the connection. According to the original draft of the protocol, the server should send an OUT in response, but in practice, it never does.

Server Closes Connection

Sometimes the server will initiate the closing of the connection. This can happen for two reasons: either the server is going down, or someone logged into MSN with your account elsewhere.

When someone logs into your account elsewhere, the original connection will be closed, and the new one will be connected. Before closing the connection, the NS will send the client the OUT command with the parameters OTH - the principal logging in from another location.

When the server is going down for maintainence, it will send OUT SSD - server shutting down. The server will close the connection immediately after sending this command.

Often, before sending OUT SSD, the server will send a warning message. For example, you might see in MSN Messenger, "The server will be shutting down for maintenance in 5 minutes." These messages are described here.