April 23-27, 2002 - Version 1 - Draft 2

MSN Instant Messenger Protocol

Overview Basics Connecting Session Messaging File Transfer Other FAQ Research
This page is not officially part of the original documentation, but is only here because I forgot to remove the link to it when updating some PHP scripts.


This page was contributed by Andrew Sayers. It discusses features of MSN Messenger which we only half understand. If you have any evidence or ideas about these topics, please let us know!

Though some of the features discussed below are quite well understood, these pages are intended as a summary of what is known, not the basis for an implementation. If any of these features interest you, please read the discussions in the forum, which contain many more examples and theories.

System messages

Very rarely, MSN Messenger sends MSGs with content-type "application/x-msmsgssystemmessage". This topic was discussed in the phorum here and here.

What we know

The format of these messages is presented below. Variable parts are in red:

MSG Hotmail Hotmail <message-length>
MIME-Version: 1.0
Content-type: application/x-msmsgssystemmessage

Type: <number>
Arg: <number>

The "Type" field is obviously the type of system message. The only type we've seen so far is Type 1. This message says that the server will go down for maintenance in <arg> minutes.

What we still need to know

What other types of messages exist, and what do they mean? Presumably, there is more than one possible type of message. What are the other types?

JD suggested that some answers might lie in the official client's string-table. MSN Messenger uses the C function "printf()", which uses %n to mean "The nth supplied string", \n to mean "newline" and \" to mean a literal ". I've coloured the messages to suit.

"System Message"
"%1 Maintenance Alert %3"
"%3 will shut down for maintenance in %1 minute(s).\nYou will automatically be signed out at that time. Please finish any\nconversations in progress.\n\nAfter the maintenance has been completed, you will be able to\nsuccessfully sign in."
"%3 will shut down for maintenance in %1 minute(s).\nYou will automatically be signed out at that time. Please finish any\nconversations in progress.\n\nAfter the maintenance has been completed, you will be able to\nsuccessfully sign in."
"%1 is having network problems and is no longer in the conversation. The last few messages may not have been received."
"This conversation has been inactive; some participants will be removed."
"To resume the conversation, reinvite the people who have been removed."
"%1 has been removed."
"You are having temporary network problems and are no longer in this conversation."
"%1 would like to send you the file \"%2\" (%5 Kb). Transfer time is less than %6 minutes with a 28.8 modem. Do you want to %3 (Alt+T) or %4 (Alt+D) the invitation?"
"Waiting for %1 to accept the file \"%2\" (%5 Kb, less than %6 minutes with a 28.8 modem). Please wait for a response or %3 (Alt+Q) the file transfer."
"Transfer of file \"%2\" has been accepted by %1. Starting transfer..."
"%1 has canceled the file transfer."
"Transfer of file \"%2\" has been declined by %1."
"Transfer of file \"%2\" from %1 has been accepted. Starting transfer..."
"You have canceled the file transfer."

Notice that strings 2082 and 2083 are identical and correspond to type 1. That suggests that string 2084 might correspond to type 2 or type 3.

On the other hand, 2082 and 2083 are notification server messages where %1 is a number. 2084 is a switchboard message where %1 is presumably a username. This would suggest that either there is only one type of system message or Arg can be a string.

Notification command

MSN Messenger supports receiving (but not sending) of alert messages, for example from http://calendar.msn.com. This command was analysed by Daniel Winter and Kevin. In the official client, you can register this service by: click the golden bell tab under the msn(green buddy) tab at the left side of your messenger, and click sign on.

What we know

The format of this command (variable parts in red, indentation added) is:

NOT <message-length>
<NOTIFICATION ver="<version-number>" siteid="<siteid-number>" siteurl="<Base-URL>" id="<ID-number>">
 <TO pid="<4-byte-hex-number>:<4-byte-hex-number>" name="<your-passport>"/>
 <MSG pri="" id="<ID-number>">
 <ACTION url="<Relative-URL>"/>
 <SUBSCR url="<Relative-URL>"/>
 <CAT id="<Cat-number>"/>
 <BODY lang="<Language-number>" icon="<Icon-URL>">

Clicking on a notification message should cause a browser to go to the web site "Base-URL" + "Relative-URL"

ID-number is like a transaction ID - a number which increases for every notification in the current session

What we still need to know

What do the other fields mean? Are they used, and if so, where? Which elements are always there, and which are optional?


It's possible to plug new applications into MSN Messenger. Presumably, this is done by using the invitation command. How to plug applications into the official client is discussed here.

What we still need to know

How do plugins behave in general? How do you write a plugin for the official client?

MSN Protocol version 8

Version 8 of the MSN protocol has recently come out. It has several improvements over version 7. One of them is the replacement of the old MD5 hash with Microsoft's passport infrastructure.

Passport is no doubt documented somewhere online, but I don't know where it is. Anyone that's interested in the search might find these starting points useful: A critical security analysis of Passport, MSDN's description of C# objects and functions for passport-enabled servers.

Dave Woods has a page discussing version 8 of the MSN protocol at http://chat.solidhouse.com.

Sending messages while appearing offline

Frixon discovered this bug here. Even though it is quite well understood, bugs are liable to be fixed without notice, so cannot be relied upon in an implementation.

Your presence state is handled by your notification server. Messages are sent through switchboard servers. If you close the connection to your notification server without closing the connection to your switchboard server(s), you will still be able to send messages, but will appear to be off-line.

Detecting hidden useres

The MSN Messenger protocol tries to ensure you cannot detect the difference between an off-line user, a user appearing off-line and a user who has blocked you. However, several bugs and unfortunate necessities mean you can sometimes get information to differentiate between them.

Offline without ever going Online

When someone logs in as invisible, no presence message is sent. If they change modes to invisible, MSN Messenger will send an FLN message. When they go off-line, MSN Messenger will send an FLN message. If you receive an FLN from someone without receiving an NLN first, it indicates that they previously either logged in invisbly or changed their mode to invisible.

Limitations: this can only detect that a user was invisible before sending the message - the message most likely means that the user really is offline now. This bug could easily be fixed by Microsoft, so cannot be counted upon.

Phone numbers

Edward Bleech, here, noted that you always get "" when you request the phone number of anyone that's blocking you. If the server has already sent you non-empty phone numbers, it will send BRPs to change them to "". In short, when you see this from the server:

FLN <Blocking-passport>
BPR <List-Version+1> <Blocking-passport> PHH
BPR <List-Version+2> <Blocking-passport> PHW
BPR <List-Version+3> <Blocking-passport> PHM

With each command being sent immediately after each other and each list version one greater than the last. When you are unblocked, the server will send the opposite information:

NLN <Unblocking-passport> <Unblocking-name>
BPR <List-Version+1> <Unblocking-passport> PHH <Home-phone-number>
BPR <List-Version+2> <Unblocking-passport> PHW <Work-phone-number>
BPR <List-Version+3> <Unblocking-passport> PHM <Mobile-phone-number>

This is a very strong sign that you've been blocked. However, it is possible (if highly unlikely) for this to happen innocently. On the other hand, if you have someone's phone numbers, that proves they aren't blocking you.

This behaviour is NOT a bug in the protocol. In the official client, this will hide personal information from prying eyes. Not sending these commands would be a breach of privacy.

Limitations: This method does not work if you are offline when someone blocks you. This method can only be used to detect blocks from people who have set their phone numbers.

CAL error

Here, om3ga noted that when you send a CAL message to bring a user into a switchboard, the server will send you error 217 (user not online) if they are really off-line, or 216 (User already on list) if they are on-line but just hiding.

Mobile Device

Jason noticed that an invisible or offline user who uses MSN Mobile may still allow you to them send messages through MSN Mobile, but that a blocking user will not. It remains to be seen whether MOB, MBE, or both are reset when the user goes offline. It may be that this can be used like Edward Bleech's phone-number method to detect a block.

Andrew Sayers

Copyright ©2002-2003 to Mike Mintz.