Since March 10, 2003 - Version 2.1

MSN Messenger Protocol

General - Overview

Back To Normal Layout

What is MSN Messenger?

The term "MSN Messenger" is quite ambiguous, as Microsoft use the term to refer to several different parts of their instant messaging solution. You chat over the "MSN Messenger network", the most popular program to connect to the MSN Messenger network is "MSN Messenger", and the language that programs on the MSN Messenger network speak is the "MSN Messenger protocol".

What is the MSN Messenger network?

The MSN Messenger network is a presence and instant messaging network from Microsoft. It went online in July 1999, and is neither the first nor the last instant messaging network. MSN is among the top four proprietary instant messaging networks. As of March, 2003, there were far less unique users on the MSN Instant Messenger network than on AOL Instant Messenger or ICQ but more than Yahoo Messenger.

What do programs on the MSN Messenger Network do?

The program on your PC is called an MSN Messenger "client". It connects to an MSN Messenger "server" over the Internet. In broad terms, the client then sends and receives information with other clients via the server. Most of the time, your client will converse with the MSN Messenger server, which processes the information and tells other people. However, some information is simply passed on by the server without being processed. For example, when sending an instant message, the command "here is a message, pass it on" is processed by the server, but the message itself is just passed on by the server and processed by the client.

Microsoft have released two MSN Messenger clients: MSN Messenger (also known as ".NET Messenger") and Windows Messenger. Microsoft recommends MSN Messenger for most Windows users, except on Windows XP, where Windows Messenger is bundled with the operating system. Other people and companies have written "third party" MSN Messenger clients. You can see some of them listed on the resources page. MSN Messenger is generally considered the de-facto standard client, and most clients take their lead from its behaviour, so it's referred to as "the official client" on this site.

Microsoft have never publicly released their Messenger server, and the official client doesn't allow you to connect to servers other than those operated by Microsoft. Still, some people have written third party servers, which can be found on the resources page.

The "language" used in communication between two computer programs is called a "protocol". The rules for messages sent between MSN Messenger clients and servers is called the "MSN Messenger protocol". The rules for messages sent from one client to another through the server is referred to on this site as the "MSN Client protocol".

What is the MSN Messenger protocol?

The MSN Messenger protocol consists of a series of commands sent between the client and the server. For example, when someone on your contact list goes offline, the servers sends a message like this to your client: FLN On receiving this, the client should take that user out of the list of on-line users and put it into the list of offline users.

The MSN Messenger protocol has undergone several revisions over the years. At the time of writing (November 2003), Microsoft's servers allowed clients to use versions 8, 9, and 10 of the protocol. Individual protocol versions are often written as "MSNP8", "MSNP9" and "MSNP10".

This site intends to fully document the MSN Messenger protocol and quirks of MSN Messenger servers so that third party software developers can write their own programs to interact with the network. At present, only MSNP8 is documented, though there some discussion is available for MSNP9 and MSNP10.

The information on the protocol was gathered by reading the official IETF draft, reading various sources, analysing packets, analysing the official client, and writing programs. Most of this work was done by other members of the MSN Messenger research community, which we have just written up. If you have discovered something new about the protocol, please make it known on the forum.

What is the MSN Client protocol?

The MSN Client protocol consists of messages sent between clients. For example, when you say "hello" to a friend, your client sends a message to their client with hello as the body of the message.

Until relatively recently, the MSN client protocol grew quite organically - one version of the official client would behave differently to another, and you just had to guess what behaviour was expected by whom. Recently, attempts have been made to impose a version numbering system. As of November 2003, three versions of the MSN Messenger client protocol have been observed, which are referred to on this site as "MSNC0", "MSNC1", and "MSNC2".

This site intends to fully document the MSN client protocol and quirks of the official client so that third party software developers can write their own programs to interact with the network. We hope to fully document all versions of the protocol eventually. This site only documents the behaviour of the official client in so much as it informs us about how other clients are expected to behave. The authors of this site don't use the official client, so wouldn't do justice to the subject. There are other sites that cover this topic well.

What do Microsoft think about all of this?

We have no connection with Microsoft, and only very limited communication. We know that at least some Microsoft employees are aware of this site and the community in general, but corporate policy seems to be one of ignoring us. Microsoft haven't made any serious attempt to keep third party clients out of their network, but they've also never attempted to talk with us or give assurances about the future. They've been very receptive about reports of bugs that have security implications.

Compared to AOL (which owns both AIM and ICQ), Microsoft is very nice to the third party developers of its protocol. This probably doesn't reflect any great philanthropy on their part: third party clients boost the number of users on Microsoft's network and (unlike with AOL) we don't represent a direct threat to their revenue stream.

How does the protocol work?

MSN Messenger is a presence and instant messaging system. "Presence" is whether you're on-line, whether you're sharing a webcam, etc. "Instant messaging" is talking with other people. Users of presence and instant messaging systems (people, bots, etc.) are referred to as "principals". RFC 2778 provides a very good general overview of what a presence and instant messaging system does, and you're advised to read it if you haven't worked on one before. Where possible, technical terms used on this site have been taken from that document.

An MSN Messenger session involves a connection to a "notification server" (or "NS"), which provides a presence service. The notification server allows you to connect to "switchboard servers" ("SB"s) which provide an instant messaging service.

Notification Server (NS)

The connection to a notification server is the basis of an MSN Messenger session, as it handles your presence information: if you are disconnected from the notification server, you are no longer online to your buddies. The main purpose of the notification server is to handle presence information about yourself and the principals whose presence you've subscribed to.

The notification server also performs some other services like notifying you about new e-mail in your hotmail inbox and letting you create new (or join existing) switchboard sessions. When you're directed to join a switchboard session, you should open a new connection to the switchboard, and keep the notification server open.

Note: The original draft refers to a third type of server known as a Dispatch Server, or "DS". However, throughout our documentation, the Dispatch Server is just treated as the default notification server.

Switchboard (SB)

The switchboard handles instant messaging sessions between principals. In other words, each person in an MSN chat corresponds to a connection to a shared switchboard session. Being in two conversations at once means connecting to two switchboard servers at once. Directly connected conversations between principals are not used in MSN Messenger, and the switchboard acts as a proxy between you and those you are chatting with.

A switchboard session can have as many people in it as you like - there's no equivalent of the one-to-one conversations that there's no way of forcing a session not to accept more than two people. This can be quite awkward because some of the uses for a switchboard session (like initiating a file transfer)

The SB is also where invitations to other services such as file transfer and NetMeeting are sent and received. Mobile paging is one of the only forms of communication that does not take place over a switchboard server.

Note that the SB and the NS are not very tightly integrated. For example, when a principal in a switchboard session change his or her display name, the switchboard still sends out messages and other commands with the old display name. In addition, when a principal disconnects from the NS, all switchboard sessions still remain open until the client explicitly closes them.

What syntax is used in this document?

Raw Protocol

This site includes many examples of dialogues between client and server, and between two clients. Client/server dialogues are always described from the point-of-view of the client. Client/client dialogues are described from the point-of-view of one or other client. A bold monospace font is always used for these dialogues. Text sent from the (local) client is always blue. Text sent from the server (or the other client) is always green. Information about the dialogue is always bluish green.

A block of text sent by the (local) client is always preceded by >>> followed by a space. A block of text sent by the server (or the other client) is always preceded by <<< followed by a space. Other information is always preceded by <o> and a space.

At the end of a line of text sent by the server or the client, there are often newline characters. In most cases, it is a carriage return followed by a linefeed which is expressed as the light-grey \r\n. Note that this is two bytes, and is not the literal characters "backslash R backslash N". Special attention should be paid to newlines, as the simplest (and most common) programming mistakes in the Messenger protocol involve putting a newline where there shouldn't be one, forgetting to put one where there should be one, or mis-counting the size of a newline.

When short examples of protocol are found in paragraphs, such as the name of a command or an example of a nickname, they are usually found in a bold monospace red font.

Copyright ©2002-2004 to Mike Mintz.