A contact list can mean many things. Most people think of the contact list as the list of buddies that shows up in the main window whenever they log into MSN. In terms of the protocol, there are four main lists where information about buddies is stored, as well as a list of groups, your phone numbers, and some privacy settings.

When the official client logs on, the first thing it does is send the SYN command to retrieve everything on the contact list. This page will explain that command and all of the information from the server sent in response.

Important Terms

Before we go into details about the protocol, there are some terms you must know.

List Version

Your entire contact list has a version number. Every time a single change is made to the contact list, either initiated by the server or by the client, that number is incremented. The purpose of this number is to ensure that the client and server have the same version of the list. A client may cache the entire contact list, just as the official MSN client does, and if no changes have been made, log on without downloading all of the lists.

This number doesn't have an official name, and some people might use other terms for it, such as list modification number. This number must between 0 and 4294967295 (2^32 - 1).

Forward List (FL)

The forward list, abbreviated as FL, is the list of contacts that you have added to your contact list. This is the list that is displayed whenever you sign on to MSN. When people think of their contact list, they think of this particular list.

This list currently (as of March 23, 2003), has a limit of 150 users, as doubled from a previous 75. If you try to add a 151st user, you will receive error 210 and the user will not be added.

Reverse List (RL)

The reverse list, abbreviated as RL, is the list of other users that have you on their forward list. You cannot make modifications to it. If you attempt to add or remove users from this list, you will be immediately disconnected from the NS with no error message.

Allow List (AL)

The allow list, abbreviated as AL, is the list of users that you allow to see your online presence - as opposed to your reverse list, which is the list of users who request to see your online presence. If someone removes you from his or her contact list, he or she is automatically removed from your RL but not your AL. He or she no longer receives online presence from you, but if he or she adds you again, your client can act in the knowledge that you previously allowed him or her to see your presence.

Block List (BL)

The block list, abbreviated as BL, is the list of users that are blocked from seeing your online presence. They will always receive FLN as your status, and when they try to invite you to a switchboard session, they will always be notified that you are offline. A user cannot be on the AL and the BL at the same time, and if you try to add a user to both lists, you will receive error 219.

Group List

This was added in recent versions of the MSN protocol and official client. This is a list of groups that your forward list is divided into. Because this is a list of words and corresponding ID numbers and not a list of users, this list is not one of the four main lists and is treated differently.

Group ID

Every group on your contact list has an identification number associated with this. The client and server use this number when referring to each group instead of the group name.

Phone Numbers

Another addition to the protocol since its first incarnation is phone numbers. [HOW DO DIFFERENT PROTOCOL VERSIONS TREAT PHONE NUMBERS DIFFERENTLY?] The server sends you your phone information with SYN automatically, as well as the phone numbers of every user on your FL. Note that each user can decide whether or not to put up their phone numbers, so there is no big privacy issue with it.

SYN

The SYN command is used to synchronize all four lists, the group list, your phone numbers, and some privacy settings with the server. The official client sends this right after it logs on and before it sets its initial status. SYN stands for synchronization.

A client can request each list separately to save bandwidth, but without sending SYN, a client will not receive list modification notifications. Currently, the only notifications sent are when a user is added or removed from your RL (when they add or remove you from your list).

Sending SYN

If the client stores a cached version of the list after it logs off every time (as the official client does), it can send its list version number along with the SYN. If no changes have been made to the contact list since then, giving the server the same list version, the server will not send the list to the client. This saves a lot of time and bandwidth. If the version numbers do not match, the server will just send the entire list anyway.

If the client does not keep a cached version, it can just send zero as the list version and receive the entire list. It can take quite a while to download the entire contact list. The response to SYN for my account is over 50 kilobytes, which can take over ten seconds on a slow connection. It might be best to send SYN before setting your initial status so that other users will not have to wait for you to download your list before you can receive their messages.

To use the SYN command, just send it with a TrID and your list version number as the parameter. Below are two examples.

>>> SYN 12 2194\r\n

>>> SYN 13 0\r\n

SYN Responses

The first thing the server sends in response to the SYN is another SYN command. It will look exactly like what you sent the server, except it will have the current list version. If this number is the same as the version you sent, then the synchronization has ended and you can use your cached list. Otherwise, it will continue.

Note that every response to the SYN has the same TrID as the one you sent. No other messages from the server will be sent until the synchronization is complete.

After sending the SYN, the server will send all of the information in a particular order. Each part of the response will be described below. The order is always as follows:

GTC
BLP
PRP
LSG
LST FL
LST AL
LST BL
LST RL

Of course, this does not include the initial SYN response. You know that the synchronization is complete when you receive the last entry in LST RL. Below is an example of the entire SYN query and response. Note that it is divided into smaller sections so it's easier to see how it is organized, but it just comes as one big string of data from the server.

Example SYN Response

>>> SYN 54 0\r\n

<<< SYN 54 12182\r\n <<< GTC 54 12182 A\r\n <<< BLP 54 12182 AL\r\n <<< PRP 54 12182 PHH 555%20555-0690\r\n <<< PRP 54 12182 PHW\r\n <<< PRP 54 12182 PHM\r\n <<< PRP 54 12182 MOB N\r\n <<< PRP 54 12182 MBE Y\r\n <<< LSG 54 12182 1 3 0 Other%20Contacts 0\r\n <<< LSG 54 12182 2 3 2 Group1 0\r\n <<< LSG 54 12182 3 3 5 Group2 0\r\n <<< LST 54 FL 12182 1 2 example@passport.com Mike 0\r\n <<< BPR 12182 example@passport.com PHH\r\n <<< BPR 12182 example@passport.com PHW 555%20555-1234\r\n <<< BPR 12182 example@passport.com PHM I%20Dont%20Have%20One\r\n <<< BPR 12182 example@passport.com MOB N\r\n <<< LST 54 FL 12182 2 3 name_123@hotmail.com Name_123 1,2\r\n <<< BPR 12182 myname@msn.com PHH\r\n <<< BPR 12182 myname@msn.com PHW\r\n <<< BPR 12182 myname@msn.com PHM\r\n <<< BPR 12182 myname@msn.com MOB N\r\n <<< LST 54 FL 12182 2 2 myname@msn.com My%20Name 2\r\n <<< BPR 12182 myname@msn.com PHH 555%20555%204321\r\n <<< BPR 12182 myname@msn.com PHW I%20AM%20DUMB\r\n <<< BPR 12182 myname@msn.com PHM\r\n <<< BPR 12182 myname@msn.com MOB Y\r\n <<< LST 54 AL 12182 1 3 myname@msn.com My%20Name\r\n <<< LST 54 AL 12182 2 3 example@passport.com Mike\r\n <<< LST 54 AL 12182 3 3 name_123@hotmail.com Name_123\r\n <<< LST 54 BL 12182 0 0\r\n <<< LST 54 RL 12182 1 2 myname@msn.com My%20Name\r\n <<< LST 54 RL 12182 2 2 name_123@hotmail.com Name_123\r\n

Privacy Settings

There are two privacy settings stored in the contact list: GTC and BLP.

GTC

The GTC setting stores a value on the server to be retrieved by the client every time it logs on. This setting has only two values: A and N. This setting is only stored by the server and is not processed in any way. Only the client sees it and decides what to do based on its value.

The client is expected to use this value as how to behave when a new user is added the the RL. If the value is set to A, the client should prompt the user about whether to add this user to the AL or the BL. If the value is set to N, the client should automatically add the user to the AL. The default setting is A. Note that it is still the client's job to add the user to one of the lists, and the server will not do this automatically.

The only time you can ever receive this value is during an SYN. To change it however, you must use the GTC command. Just send it with a TrID, and the new value as the only parameter. If successful, the server will return a GTC with your TrID, the new list version as the first parameter, and the new GTC value as the second parameter. If you tried to change it to the value it was already set to, you will receive error 218. If you send an invalid parameter, you will be immediately disconnected.

Here are some examples:

>>> GTC 20 A\r\n

<<< GTC 20 200 A\r\n

>>> GTC 21 N\r\n

<<< GTC 21 201 N\r\n

>>> GTC 22 N\r\n

<<< 218 22\r\n

<<< GTC 23 F\r\n

<o> Server Closes Connection

BLP

Like the GTC command, BLP setting stores a value on the server and is retrieved by the client every time it logs on. This setting also has only two values: AL and BL. Unlike the GTC command, the server actually reads this setting and does certain things differently depending on its value.

This value determines how to treat users that are not on the AL or the BL. If the value is AL, all users not on either list will be allowed to invite you to a switchboard session and chat with you. If the value is BL, any user not on either list will be informed that you are offline, and you will not receive the invitation to the switchboard. The default value is AL.

Changing this value works exactly the same way as GTC, except with a different command name and new values. Below are some examples.

>>> BLP 24 AL\r\n

<<< BLP 24 202 AL\r\n

>>> BLP 25 BL\r\n

<<< BLP 25 203 BL\r\n

>>> BLP 26 BL\r\n

<<< 218 26\r\n

<<< BLP 27 FL\r\n

<o> Server Closes Connection

Interestingly enough, when a user that is not in your AL or BL tries to invite you to a switchboard session when your BLP value is set to BL, they will receive error 216 instead of the expected error 217. Because of that, they know that you are online, but that they are either in your block list, or because of the BLP setting, automatically considered a blocked user.

Phone Numbers

A somewhat recent addition to the protocol is phone numbers. Every user can set three phone numbers, and identify if they have registered his or her mobile device with MSN Mobile.

Receiving Personal Phone Numbers

The only time you can receive the phone numbers that you have set for yourself is during a SYN. After the privacy settings have been sent, the personal phone numbers will be sent. These phone numbers arrive in five PRP commands. Each PRP has the TrID of the original SYN, the list version as the first parameter, a three letter code for the phone type as the second parameter. and the value of the phone number as an optional third parameter (does not exist if a phone number has not been set).

Here is a list of the five different phone number types in the order that they are sent:

PHH - Home Phone Number
PHW - Work Phone Number
PHM - Mobile Device Number
MOB - Are other users authorized to contact me on my mobile device?
MBE - Do I have a mobile device enabled on MSN Mobile?

The value for the first three items can be anything up to 95 characters. This value is just like a nickname and uses URL-encoding for special characters (or any characters). If there is no phone number set, there will be no third parameter.

The value of MOB and MBE can only be Y or N, representing "yes" and "no". If MOB is set to true, that shows that the client has authorized for other users to contact him on his mobile device through the PAG command. If MBE is set to true, that shows that the client has enabled a mobile device on MSN Mobile. Of course, MBE has to be set to Y in order for MOB to be set to Y. Note that these values are completely independent from the PHM mobile device number.

Below is an example of the phone numbers of a user who has set only his or her home phone number and has a mobile device but has chosen not to allow users to page him or her on MSN. Note that the home phone number is URL-encoded, and would show up like this when decoded: "555 555-0690".

<<< PRP 54 12182 PHH 555%20555-0690\r\n <<< PRP 54 12182 PHW\r\n <<< PRP 54 12182 PHM\r\n <<< PRP 54 12182 MOB N\r\n <<< PRP 54 12182 MBE Y\r\n

Setting Personal Phone Numbers

To set a personal phone number, send the PRP command with a TrID, the three letter code for the phone type, and the phone value (or no second parameter if making the phone number blank).

If successful, the server will respond with a single PRP that looks just like the one you see in the SYN.

If you send a phone number larger than 95 characters, counting a three-byte URL-encoded character as three digits, the server will immediately close the connection with no error.
If you try to set a nonexistent phone type of three or less characters such as PHV or PH, the server will respond with error 715.
Because phone types are case sensitive, trying to set phh will also result in error 715.
If the phone type is larger than three characters, the server will immediately close the connection.

If you try to set MOB to anything when MBE is set to N, the server will respond with MOB still being set to N and no changes will be made. You can set MBE to Y even if you do not have a mobile device set up, which doesn't make much sense. You can also set MBE to N and leave MOB still as Y.

If you set either MOB or MBE to something besides Y or N, the server will set it to N, regardless of what it says in its response. There are a lot of weird exceptions to all of this, so just try to keep weird things from happening.

Below are some examples of setting personal phone numbers:

>>> PRP 55 PHH 555-1234\r\n

<<< PRP 55 12183 PHH 555-1234\r\n

>>> PRP 56 PHW\r\n

<<< PRP 56 12184 PHW\r\n

>>> PRP 57 PHV 1234\r\n

<<< 715 57\r\n

>>> PRP 58 MOB Y\r\n

<<< PRP 58 12185 MOB Y\r\n

Receiving Phone Numbers of Other Users

As well as your own phone numbers, you will receive the phone numbers of every user in your FL during an SYN. These will arrive as BPRs and are in the same order as the personal numbers, except MBE will not be included. Also, there are no TrIDs and between the list version and the phone type, the user's account name will be included as a parameter. If a user has MOB set to Y, that means that you can page them with the PAG command. All four PRPs will arrive for each user after the individual LST entry has been sent for that user. This will be discussed in more detail later on in this page with the LST information.

Group List (LSG)

After the five PRPs have been sent, the NS will send the list of groups in your contact list with the LSG command. If you want to receive this list separately, outside of an SYN, just send the LSG command with a TrID and no parameters, and you will receive the list of groups in the same format.

The LSG command is an example of a "list command" described in the Commands page. The NS will send one LSG for each group. Each LSG will contain the TrID, followed by the list version, an incrementing number, the total number of groups, an identification number of the group, the URL-encoded name of the group, and a static zero.

The incrementing number starts at 1 and is incremented for every LSG. On the final LSG, the incrementing number should match the total number, which represents the total number of groups. The identification number is a number the client and server refer to the group as. The group name is URL-encoded just like a nickname. The final parameter should always been a zero, however it could theoretically be any number.

If the user has not added any groups, the default group name and ID is ~ (tilde) and 0 (zero) respectively. Below are some examples:

>>> LSG 15\r\n

<<< LSG 15 5 1 1 0 ~ 0\r\n

>>> LSG 45\r\n

<<< LSG 45 12187 1 3 0 Other%20Contacts 0\r\n <<< LSG 45 12187 2 3 2 Group1 0\r\n <<< LSG 45 12187 3 3 5 Group2 0\r\n

User Lists (LST)

After sending the LSG, the NS will send all four lists in the order of: FL, AL, BL, RL. The entire synchronization process is complete when the last RL item has been received.

Each list has exactly the same format, with two exception: after every entry in the forward list, there are four BPRs sent with the phone information of each user. Also, as the last parameter for every item in the FL, there is the group ID for the group that each user belongs to. If the user belongs to more than one group, the IDs will be separated by commas (like 0,3,4), and is always in incremental order, but as a client developer you should not rely on that being true. This parameter will only be sent if you are using MSNP7 (or possibly later versions).

The LST command, like the LSG command, is another example of a "list command" as described in the Commands page. The format for each LST is very similar to the format for LSG.

The first parameter is the two letter list code.
The second parameter is the list version.
The third parameter is the incrementing number.
The fourth parameter is the total number.
The fifth parameter is the account name.
The sixth parameter is the user's nickname. (For more information on nicknames, see the Names page.)
If the list is an FL and you are using MSNP7, there will be an additional seventh parameter for the group ID. The default group ID is zero.

If there are no users in a list, both the incrementing number and the total number will be zero, and you will only receive one entry for that list. Other than that, the incrementing and total numbers work the same way as the do in the LSG command. As soon as you receive the last reverse list item, the synchronization is complete. The official client then looks at the RL, and if there are any items in the RL that are not in the AL or the BL, the client will treat that user as having just added you and display a popup window (or not, depending on the value of GTC). There are some programs out there that erase everyone from your allow list so that you can appear offline to people while you talk, but when users log back on again, they are often flooded with many of these popup windows.

User Phone Numbers (BPR)

After each item in the forward list, you will receive a list of four BPRs for the phone numbers of the user. This is very similar to the format of the PRPs for personal phone numbers, it just leaves out MBE, adds an additional parameter for the user's account name, and does not contain TrIDs. There is no way to request BPRs individually. When a user updates their phone numbers, you will receive a BPR with your contact list ID incremented by one. If a user updates several phone numbers at once, you will receive several BPRs in succession, each with a contact list ID one greater than the last.

Here is an example of receiving phone numbers after an FL listing in the synchronization:

<<< LST 54 FL 12182 1 2 example@passport.com Mike 0\r\n <<< BPR 12182 example@passport.com PHH\r\n <<< BPR 12182 example@passport.com PHW 555%20555-1234\r\n <<< BPR 12182 example@passport.com PHM I%20Dont%20Have%20One\r\n <<< BPR 12182 example@passport.com MOB N\r\n

When someone changes their phone number in the middle of a session, the NS will send you their updated phone number outside of an SYN like this:

<<< BPR 12183 example@passport.com PHH 555%20555-4321\r\n

All four BPRs will also be sent after adding a new user to your FL. However, no matter what values the new user has set these to, you will receive blank values for everything unless you are already on their AL. If you are on their AL, you will receive correct values for each one (and if they are online, you will receive an ILN). Otherwise, you will receive blank BPRs at first, then updated BPRs when they add you to their AL.

It is interesting to note that if you have phone numbers set and you block someone, they will receive all four BPRs that have been set to blank (or if they are offline, the FL will just have blank phone numbers). This only applies if some phone numbers are actually set.

LST

To receive lists outside of SYN, just send the NS the LST with a TrID and the two letter list code. Note that list codes are case sensitive, and if you send an invalid list code, like VL or al, you will be immediately disconnected. If sent correctly, the server should respond with the entire list, and nothing more. The FL will include all of the phone numbers as well.

Below is an example of requesting the AL:

>>> LST 66 AL\r\n

<<< LST 66 AL 12182 1 3 myname@msn.com My%20Name\r\n <<< LST 66 AL 12182 2 3 example@passport.com Mike\r\n <<< LST 66 AL 12182 3 3 name_123@hotmail.com Name_123\r\n

Here is an example of requesting the FL:

>>> LST 67 FL\r\n

<<< LST 67 FL 12182 1 2 example@passport.com Mike 0\r\n <<< BPR 12182 example@passport.com PHH\r\n <<< BPR 12182 example@passport.com PHW 555%20555-1234\r\n <<< BPR 12182 example@passport.com PHM I%20Dont%20Have%20One\r\n <<< BPR 12182 example@passport.com MOB N\r\n <<< LST 67 FL 12182 2 3 name_123@hotmail.com Name_123 2\r\n <<< BPR 12182 myname@msn.com PHH\r\n <<< BPR 12182 myname@msn.com PHW\r\n <<< BPR 12182 myname@msn.com PHM\r\n <<< BPR 12182 myname@msn.com MOB N\r\n <<< LST 67 FL 12182 2 2 myname@msn.com My%20Name 2\r\n <<< BPR 12182 myname@msn.com PHH 555%20555%204321\r\n <<< BPR 12182 myname@msn.com PHW I%20AM%20DUMB\r\n <<< BPR 12182 myname@msn.com PHM\r\n <<< BPR 12182 myname@msn.com MOB Y\r\n

And finally, here is an example of requesting a BL, which is empty:

>>> LST 68 BL\r\n

<<< LST 54 BL 12182 0 0\r\n

When sent in response to an SYN, these LSTs will be sent one at a time in the order of FL, AL, BL, RL. They will all have the same TrID for every item.