Clients behind some kinds of firewalls will be disconnected if they let a connection go idle for more than a certain amount of time. To stop this from happening, the client can send a regular PNG command to a server, which will respond with a QNG. A safe default is to send this message once every minute, if you have sent nothing else in that time. Note that there are no transaction ID's used, but the \r\n exists in both the request and the response. The format is as follows:
>>> PNG
<<< QNG
Challenges are commands from the server that are sent at random times and you must acknowledge them to stay connected. Their three letter code is CHL, and they are sent with two parameters: a 0, and an MD5 hash. To acknowledge the challenge, you must send a QRY command, followed by a new transaction ID, followed by msmsgs@msnmsgr.com, followed by 32, followed by a newline, and then the hexadecimal digest of the MD5 hash concatenated with Q1P7W2E4J9R8U3S5, with no newline at the end. If this is successful, the server will reply with QRY followed by your transaction ID. If it fails, the server will send error code 540 and disconnect you. Below is an example of a successful challenge.
<<< CHL 0 15570131571988941333
>>> QRY 10 msmsgs@msnmsgr.com 32 (Newline)
8f2f5a91b72102cd28355e9fc9000d6e(No Newline)
<<< QRY 10
When the status of someone on the user's contact list changes (someone gets online, someone goes offline, someone goes out to lunch), the user is notified with the NLN and FLN commands. Both of these commands have no transaction ID's since they are asynchronous. The NLN command is used when a user is online, and has three parameters: the three letter status code, the user's passport ID, and the user's screen name. The FLN command is used when a user goes offline, and has the status code and passport ID as its two parameters. Below is an example of some status notifications
<<< NLN AWY example@passport.com Mike
<<< NLN NLN myname@msn.com My%20Name
<<< FLN name_123@hotmail.com
To change your online status, you must use the CHG command. This works exactly the same as when you set your initial status when connecting, except this will have a different transaction ID. If you send an invalid status, you will be disconnected immediately. Below are some examples.
>>> CHG 8 AWY
<<< CHG 8 AWY
>>> CHG 9 NLN
<<< CHG 9 NLN
>>> CHG 10 HDN
<<< CHG 10 HDN
Every status has a three letter code, and these must be known when changing status, or viewing other users' statuses. The list below explains what each of the 9 status codes represent.
NLN OnlineFLN OfflineHDN Appear OfflineIDL IdleAWY AwayBSY BusyBRB Be Right BackPHN On the PhoneLUN Out to LunchThere are four types of contact lists, each with a two letter code.
FL Forward List - Users on your contact list.RL Reverse List - Users who have you on their contact list.AL Allow List - Users who are allowed to see your status.BL Block List - Users who are not allowed to see your status.To request a particular list, you must use the LST command, with the two letter code of the list as the parameter. The server should respond with an LST command for every user in the requested list. Every response will have the same transaction ID. The first parameter is the two letter code of the list. The second parameter is a number respresenting the version of the list being sent (which is incremented every time there is a change). The third parameter is a number representing the user, that starts on 1 and is incremented for each user in the list. The fourth parameter is the total number of users in the list, and when the third parameter is the same as the fourth parameter, you know that the list is complete. The fifth and sixth parameters are the user's Passport and screen name respectively. When the list requested is the forward list (FL), there will be a seventh parameter representing the group ID. Nickname and Group ID will be discussed further on.
If there are no users on the requested list, the server will reply with 0 for both the user number and the total number of users, and there will be no fifth or sixth parameter. Below are some exampes of requesting lists.
>>> LST 10 FL
<<< LST 10 FL 21 1 3 example@passport.com Mike 0
<<< LST 10 FL 21 2 3 name_123@hotmail.com Name_123 2
<<< LST 10 FL 21 3 3 myname@msn.com My%20Name 0
>>> LST 11 BL
<<< LST 11 BL 3 0 0
If a user that is not on your reverse list tries to send you a message, it will either go through or fail depending on your privacy mode. To set your privacy mode, send the command BLP with either AL or BL as the only parameter. Having AL as the parameter tells the server to accept messages from every user, except those in the block list. Having BL as the parameter tells the server to accept messages from only users in the allow list. Again, the server will echo the command back if successful, or give the error 218 if the client is already in that mode.
To ask the client to prompt you every time a user adds you to their contact list, send the GTC command with a parameter of A. To have the client automatically add the user, send the command with a paramter of N. The server will echo the command back if successful, or will give error 218 if the client is already in that mode. The server only stores this value - it is the client's responsibility to add users to the AL or BL.
To request every list simultaneously, use the SYN command, with the version number of the most recently cached list you have. If you do not have an older version of the list stored, use 0 as the version to retrieve everything. If your version number is up to date, you will get an SYN reply with the same version number and that's it. Otherwise, the server will respond with the new version, every type of contact list, every privacy setting, phone numbers, and more, all using the same transaction ID. The official MSN Messenger client always syncs to retrieve contact list data, and list change notifications (user has added you, user has erased you) are not sent unless a SYN has been sent to the server, so it is recommended. The replies are sent in this order: SYN, GTC, BLP, PRP, LSG, LST FL, LST AL, LST BL, and LST RL. Below is a short example of syncing lists (new commands are explained below). Additional blank lines are added for organization, but will not be sent from the server (every line ends with a single \r\n).
>>> SYN 54 0
<<< SYN 54 12182
<<< GTC 54 12182 A
<<< BLP 54 12182 AL
<<< PRP 54 12182 PHH 555%20555-0690
<<< PRP 54 12182 PHW
<<< PRP 54 12182 PHM
<<< PRP 54 12182 MOB Y
<<< PRP 54 12182 MBE N
<<< LSG 54 12182 1 3 0 Other%20Contacts 0
<<< LSG 54 12182 2 3 2 Group1 0
<<< LSG 54 12182 3 3 5 Group2 0
<<< LST 54 FL 12182 1 2 example@passport.com Mike 0
<<< BPR 12182 example@passport.com PHH
<<< BPR 12182 example@passport.com PHW 555%20555-1234
<<< BPR 12182 example@passport.com PHM I%20Dont%20Have%20One
<<< BPR 12182 example@passport.com MOB N
<<< LST 54 FL 21 2 3 name_123@hotmail.com Name_123 2
<<< BPR 12182 myname@msn.com PHH
<<< BPR 12182 myname@msn.com PHW
<<< BPR 12182 myname@msn.com PHM
<<< BPR 12182 myname@msn.com MOB N
<<< LST 54 FL 12182 2 2 myname@msn.com My%20Name 2
<<< BPR 12182 myname@msn.com PHH 555%20555%204321
<<< BPR 12182 myname@msn.com PHW I%20AM%20DUMB
<<< BPR 12182 myname@msn.com PHM
<<< BPR 12182 myname@msn.com MOB Y
<<< LST 54 AL 12182 1 3 myname@msn.com My%20Name
<<< LST 54 AL 12182 2 3 example@passport.com Mike
<<< LST 54 AL 12182 3 3 name_123@hotmail.com Name_123
<<< LST 54 BL 12182 0 0
<<< LST 54 RL 12182 1 2 myname@msn.com My%20Name
<<< LST 54 RL 12182 2 2 name_123@hotmail.com Name_123
Whew! And that's just for three users! If you had sent an up-to-date list version number, the server would respond with just a SYN followed by the transaction ID and the version number.
>>> SYN 54 12182
<<< SYN 54 12182
One of the replies sent in the SYN command is a list of groups in your contact list. These are sent with the LSG command and are similar to the LST replies. Below is an example.
<<< LSG 54 12182 1 3 0 Other%20Contacts 0
<<< LSG 54 12182 2 3 2 Group1 0
<<< LSG 54 12182 3 3 5 Group2 0
The first parameter is the list modification number, the second and third are the incremented and total group numbers, the third number is each group's unique ID, the fourth parameter is the URL quoted name of the group, and the fifth always seems to be a 0.
Note that you can also request the list of groups separately by sending the LSG command with only a trial ID. This works just like the LST command. If you sync, there should be no reason to use this command, but it is still valid. Below is an example (note that this has not been tested; if you try this, and it works just as displayed here, please tell me so I can remove this notice).
>>> LSG 55
<<< LSG 55 12182 1 3 0 Other%20Contacts 0
<<< LSG 55 12182 2 3 2 Group1 0
<<< LSG 55 12182 3 3 5 Group2 0
When syncing lists, your stored phone numbers and the phone numbers of every user on your forward list is sent. Your stored phone numbers are sent in PRP commands. There are five numbers sent, each in their own PRP. Below is an example.
<<< PRP 54 12182 PHH 555%20555-0690
<<< PRP 54 12182 PHW
<<< PRP 54 12182 PHM
<<< PRP 54 12182 MOB Y
<<< PRP 54 12182 MBE N
PHH represents home phone number, PHW respresents work phone number, and PHM represents mobile phone number. The phone numbers are url quoted, and if none exists, there just will be no fifth term. I think MOB represents if you have a mobile pager, and is either Y (yes) or N (no). I have no clue what MBE is, but its something I don't use.
For every user on your forward list, you will receive their phone numbers while syncing. After every LST, four BPR's are sent, representing the first four PRP's (there is no MBE). These commands do not have transaction ID's, and after the list modification number is the user's Passport ID. If someone changes a phone number while you are on-line, you will receive a BPR with a new list modification number ID. Below is an example.
<<< LST 54 FL 12182 1 2 example@passport.com Mike 0
<<< BPR 12182 example@passport.com PHH
<<< BPR 12182 example@passport.com PHW 555%20555-1234
<<< BPR 12182 example@passport.com PHM I%20Dont%20Have%20One
<<< BPR 12182 example@passport.com MOB N
<<< LST 54 FL 12182 2 2 myname@msn.com Name_123 2
<<< BPR 12182 myname@msn.com PHH 555%20555%204321
<<< BPR 12182 myname@msn.com PHW I%20AM%20DUMB
<<< BPR 12182 myname@msn.com PHM
<<< BPR 12182 myname@msn.com MOB Y
To set a phone number on an account, just send PRP with a transaction ID, the type of phone number, and the URL quoted phone number. The server will reply in the same way that it did with the PRP's from the sync. Below are some examples.
>>> PRP 55 PHH 555%20555-0690
<<< PRP 55 12183 PHH 555%20555-0690
>>> PRP 56 PHW 555%20555-0691
<<< PRP 56 12184 PHW 555%20555-0691
To add a group, use the ADG command. Just send ADG followed by a transaction ID, a URL quoted group name, and a zero. The server will reply with another ADG with the same transaction ID, a new list modification number, the group name again, the new group ID, and some funny string (I don't know what it's for). Below is an example.
>>> ADG 23 New%20Group 0
<<< ADG 23 12064 New%20Group 15 =�-CC
To remove a group, use the RMG command. Just send RMG followed by a transaction ID, and the group ID number. The server will reply with another RMG with the same transaction ID, a new list modification number, and the new group ID. Below is an example.
>>> RMG 24 15
<<< RMG 24 12065 15
To rename a group, use the REG command. Just send REG followed by a transaction ID, the group ID number, the new URL quoted name, and a zero. The server will relpy with another REG with the same transaction ID, a new list modification number, the group ID, the new group name, and a zero. Below is an example.
>>> REG 25 15 New%20Name 0
<<< REG 25 12066 15 New%20Name 0
To add a user to one of the four lists (except you can't add a user to your reverse list), send the ADD command with three parameters: the two letter list code, the user's Passport, and the user's Passport again. The server should reply with ADD with 4 parameters: the two letter list code, the new contact list version number, the user's Passport and a nickname of your choosing (perhaps their passport or screen name). MSN will only store one nickname per user, so if you add example@passport.com to your AL with nickname "name1" then to your FL with nickname "name2", MSN will forget "name1". Below is an example.
>>> ADD 10 AL example@passport.com example@passport.com
<<< ADD 10 AL 101 example@passport.com example@passport.com
To add a user to your forward list, you should include a group ID at the end of the ADD command. If you do not include one, I think zero is implied. The server will reply with the group ID again at the end. The maximum is currently (as of February 21, 2003) 150 people on your forward list (doubled from a previous 75). Below is an example.
>>> ADD 11 FL example@passport.com example@passport.com 4
<<< ADD 11 FL 102 example@passport.com example@passport.com 4
If you add a user to your forward list and the user is online, you'll get an ILN message indicating their initial status when they add you to their allow list.
Removing users is exactly like adding users with the REM command, except without the nickname parameter on both the client request and the server response. Below are two examples.
>>> REM 12 AL example@passport.com
<<< REM 12 AL 103 example@passport.com
>>> REM 13 FL example@passport.com 4
<<< REM 13 FL 104 example@passport.com 4
When another user adds you to their contact list, the server will send you an ADD (only if you have synced, of course). The ADD will have a transaction ID of 0, and will have 4 parameters: RL (two letter list code (almost always RL)), the new list version, the user's Passport, and the user's nickname. A client can either ignore this, or it can send another ADD command adding the user into the allow list, or the block list.
When another user removes you from their contact list, the server sends you the same thing, except with the REM command, and no screen name (there are only 3 parameters). Below are some examples.
<<< ADD 0 RL 105 example@passport.com Mike
<<< REM 0 RL 106 example@passport.com
To block a user that is not yet in your allow list, just send an ADD adding them to your block list. If they are in your allow list, first remove them from your allow list with REM, then add them into your block list. To unblock a user, remove them from the block list, and add them back into the allow list. If you try having a user on both the block and allow lists, the server will send error 219. Below is an example.
>>> REM 14 AL example@passport.com
<<< REM 14 AL 107 example@passport.com
>>> ADD 15 BL example@passport.com example@passport.com
<<< ADD 15 BL 108 example@passport.com Mike
>>> ADD 16 AL example@passport.com example@passport.com
<<< 219 16
To move a user from one group to another, just ADD them to the new group, and REM them from the old group. Below is an example.
>>> ADD 17 FL example@passport.com example@passport.com 5
REM 14 FL example@passport.com 4
<<< ADD 17 FL 109 example@passport.com Mike 5
REM 14 FL 110 example@passport.com 4
To change your current screen name, send the REA command with your Passport as the first parameter, and your new URL quoted screen name as the second parameter. If successful, the server will respond with REA with the list modification number as the first parameter, your Passport ID as the second, and your new screen name as the third. If the server did not like your screen name (for example, it may have contained a restricted word or been more than about 129 characters long), it will reply with error 209. Below are some examples.
>>> REA 25 example@passport.com My%20New%20Name
<<< REA 25 115 example@passport.com My%20New%20Name
>>> REA 26 example@passport.com fuck
<<< 209 26
To request somebody's screen name, just send the REA command with their Passport instead of your passport, and what you think their screen name is as the screen name. The server will reply just as it did with your screen name, except with their Passport and their screen name. I'm not sure if this works with users that are not on your contact list. Below is an example.
>>> REA 25 myname@msn.com Name_123
<<< REA 25 115 myname@msn.com Name_12345
To request a new switchboard session (or chat window in the official client), send the XFR command with the parameter SB. The server should reply with XFR with fourt parameters: SB, the IP:port of the switchboard server, CKI, and a hash that you will need to remember for logging in to the switchboard server. Below is an example.
>>> XFR 10 SB
<<< XFR 10 SB 64.4.12.193:1863 CKI 16925950.1016955577.17693
When someone invites you to a switchboard session, the notification server will send you a RNG command with 6 parameters, and no transaction ID. The first parameter is the session ID. The second parameter is the IP:port of the switchboard server. The third parameter is CKI. The fourth parameter is a hash. The fifth parameter is the Passport of user who invited you, and the sixth is their screen name. You will need to remember the session ID and the hash when logging in to the switchboard server. You do not need to reply to this message. You just have to connect to the switchboard server (or you could just ignore the invitation). Below is an example.
RNG 11752099 64.4.12.193:1863 CKI 849102291.520491932 myname@msn.com My%20Name
Information on using the switchboard server is explained in the messaging section.
To log off of MSN, send OUT with no transaction ID or parameter. The server is supposed to reply with another OUT and close the socket, but I have yet to see the server send a response (not that it's very important). You could also just close the socket yourself, and it would work the same.
A server can disconnect a user for one of two reasons: the user logged in from another location, or the server is going down for maintenance. It will send the OUT command followed by one parameter: either OTH for user logging in from other location, or SSD for server going down. It will close the connection after sending the message.