MSN Instant Messenger Protocol

Connecting

When Inviting

After receiving the XFR reply from the notification server, connect to the server and port it specified. When connected to the switchboard server, send the USR command with a transaction ID and your Passport as the first parameter. The second parameter will be the hash you received from the notification server in the XFR response. If successful, the switchboard server will reply with USR with OK as the first parameter, your Passport as the second parameter, and your screen name as the third.

To invite someone into the chat, send CAL with their Passport as the only parameter. This can also be sent later to invite additional users into the chat. The server will respond with CAL with RINGING as the first parameter, and the recipient's session ID (I don't think this is important) as the second. When the user has joined the session, the server will send JOI with no transaction ID, and their Passport and screen name as the two parameters. As soon as there is anoter user in the session, you can begin sending and receiving messages. Below is an example of connecting to the switchboard server.

<o> Connect: 64.4.12.193 1863

>>> USR 1 example@passport.com 16925950.1016955577.17693

<<< USR 1 OK example@passport.com Mike

>>> CAL 2 name_123@hotmail.com

<<< CAL 2 RINGING 11752099

<<< JOI name_123@hotmail.com Name_123

<o> Continue Session . . .

When Invited

After receiving a RNG from the notification server, connect to the switchboard server it specified. When connected, send ANS with your Passport as the first parameter, the hash you received from the notification server as the second parameter, and the session ID you received from the notification server as the third parameter.

If successful, the server will respond with one or more IRO commands each with the transaction ID from the ANS. Each IRO is exactly like the LST replies. The first parameter is the incrementing participant number, the second is the total number of participants, the third is the participant's Passport, and the fourth is the participant's screen name. After the server has finished listing the participants of the chat, it will send ANS with the first transaction ID and OK as its parameter. After you have received the ANS reply, you can begin sending and receiving messages. Below is an example of connecting to the switchboard server with two users initially in the chat.

<o> Connect: 64.4.12.193 1863

>>> ANS 1 name_123@hotmail.com 849102291.520491932 11752099

<<< IRO 1 1 2 example@passport.com Mike

<<< IRO 1 2 2 myname@msn.com My%20Name

<<< ANS 1 OK

<o> Continue Session . . .

Messages

Sending Messages

To send a message to the chat, use the MSG command with a new transaction ID. The third parameter will either be U, A or N. U specifies that the switchboard will not verify that messages were received, A specifies that the switchboard will notify you when a message is received, and N specifies that the switchboard will only tell you if the message was not received. If requested, the switchboard will reply with a ACK or a NAK if a message was received or not received respectively. It will contain the transaction ID of the message sent, and no parameters. The fourth parameter is the length of the message below (including the MIME header) in bytes, so you will need to know what you are sending before you calculate this number. The maximum length for a message is 1664 bytes, and if a longer one is sent to the switchboard, it will close the connection and not send the message.

Now you can begin the MIME header. The first field of the header is MIME-Version: 1.0. For normal messages, the content type will always be text/plain, so the second field should look like Content-Type: text/plain; charset=UTF-8, although the charset part is optional.

These two fields must occur in that order, at the very top of the message. After that, the normal rules for fields apply. The official client will only include an "X-MMS-IM-Format" field, which specifies information about the font, and might look like this: X-MMS-IM-Format: FN=Microsoft%20Sans%20Serif; EF=I; CO=000000; CS=0; PF=22. It may also include RL=1.

FN

URL-encoded name of font

EF

which of the four effects are being used (Bold, Italic, Strikeout, and Underline). If multiple effects are used, they are concatenated together, like BISU. If no effects are used, just leave no space between the = and the ;.

CO

hexidecimal BBGGRR color of the font. Note that this is the other way round to HTML's RRGGBB values. Also, 0's on the left are optional, so "0000FF", "00FF" and "FF" all mean "red"

CS

Charset (refer to the table below)

PF

Hexadecimal value for pitch and family used in both richedit and logfont. I really don't know anything about this, but Tristan explains this very well on the Discussion Forum. If this link becomes at sometime broken (like I change forums), feel free to contact me.

RL

Right-to-left script. Language is written right-to-left (e.g. Arabic, Hebrew) instead of left-to-right (English, French)

After the header, send two newlines, and then the body of the message. Below is an example.

MSG 3 A 157
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
X-MMS-IM-Format: FN=Microsoft%20Sans%20Serif; EF=I; CO=000000; CS=0; PF=22

Hello! How are you?

ACK 3

Emoticons are transmitted as plain-text. A complete list of emoticons and their plain-text encoding can be found here

Message Charsets

This information is here thanks to Slayeh.

Each font supports its own, unique set of character sets. Check with the font vendor to determine which character sets are supported. The following table lists the predefined constants provided for standard character sets.

Sending Typing Notifications

To tell the other participants of your switchboard session that you are typing a message, you will send another MSG, but with a different content type. The content type should be text/x-msmsgscontrol and I don't think you are supposed to send the UTF-8 charset. On the third field of the MIME header, send TypingUser: example@passport.com with your Passport. You can kind of spoof the server by sending a fake name and the other participants might think somebody else is typing the messsage. The body of the message will just be a newline. Below is an example.

MSG 3 U 93
MIME-Version: 1.0
Content-Type: text/x-msmsgscontrol
TypingUser: example@passport.com

(Newline)

The official MSN Messenger client will send a "User is typing" message once every five seconds, so long as you keep typing (walking away from a non-empty input box will not cause further messages to be sent). It will display an incoming "User is typing" message for 10 seconds before assuming that the user has stopped typing. There is no "user has stopped typing" message.

Sending Application Invitations

When sending application invitations such as file transfer, voice chat, and NetMeeting, use the content type text/x-msmsgsinvite. More details on using individual applications will be discussed in other sections.

Receiving Messages

When another user sends a message (whether it be text, typing, or invitation), the switchboard will send you a MSG with no transaction ID. There will be three parameters: the sender's Passport, the sender's screen name, and the length of the message. Following this line will be the message, and it will look the same as what the user's client sent. Below is an example.

MSG example@passport.com Mike 157
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
X-MMS-IM-Format: FN=Microsoft%20Sans%20Serif; EF=I; CO=000000; CS=0; PF=22

Hello! How are you?

Ending a Session

When a User Leaves

When a participant leaves a chat session, even if they are the only other user, the switchboard will send BYE with no transaction ID and their Passport as the only parameter. Below is an example.

<<< BYE example@passport.com

Leaving a Session

To leave a session, just like with the notification server, send OUT with no transaction ID, or just disconnect from the server.