MSN Messenger Protocol
What does this page cover?
This page explains how to retrieve your personal details from MSN Messenger. This includes information about people on your contact list, a list of groups they can belong to, your personal phone numbers, and some privacy settings.
When the official client logs on, the first thing it does is send the
These are the basic concepts in MSN's personal information.
Your complete set of personal details has a version number. Every time a change is made to the contact list, either initiated by you or by someone else, that number is incremented. If your details are changed then changed back (even while you're offline), the number will be incremented twice.
The purpose of this number is to ensure that the client and server have the same version of the contact details. Clients should cache all contact details. When the client logs on, if no changes have been made since it last logged off, it can avoid downloading all of your personal details. The number is always between 0 and 4294967295 (2^32 - 1).
The forward list, abbreviated as FL, is the list of principals whose presence you are subscribed to. You can expect to be notified about their on-line state, phone numbers, etc. This is what a layman would call their "contact list".
This list currently (as of March 23, 2003), has a limit of 150 people, doubled from a previous 75. If you try to add a 151st person, you will receive error 210 and they will not be added.
Everyone in your forward list belongs to one or more groups, identified by their group number. By default, they belong to group 0.
The reverse list, abbreviated as RL, is the list of principals that have you on their forward list. You cannot make modifications to it. If you attempt to add or remove people from this list, you will be immediately disconnected from the NS with no error message.
The allow list, abbreviated as AL, is the list of principals that you allow to see your online presence - as opposed to your reverse list, which is the list of people 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.
The block list, abbreviated as BL, is the list of people that are blocked from seeing your online presence. They will never receive your status, and when they try to invite you to a switchboard session, they will be notified that you are offline. No-one can be on the AL and the BL at the same time, and if you try to add someone to both lists, you will receive error 219.
This is a list of groups that people on your forward list can belong to. Every group has a name and a ID number. You are guaranteed to have at least one group defined (which everyone on your contact list belongs to by default). The default name for this list is "~".
The client and server always refer to groups by number rather than name.
MSN Messenger allows you to advertise your personal, home, and work phone phone numbers as well as your MSN Mobile and MSN Direct devices if you have them. You should be automatically sent phone number information about people in your
It can take quite a while to download all the personal details - over ten seconds for a large list on a slow connection. It might be best to send
Here are two examples of the
If the cache is up-to-date, the synchronisation has ended and there will be no further responses to the command. Otherwise the server will send these extra responses (in this order):
None of these responses will have TrIDs
Example SYN Responses
In this example, the cached version is "125", which the server verifies as up-to-date.
In this example, the client hasn't stored a cache, so the server sends a full list. The gaps in the response have been inserted to make reading easier. There are no blank lines in the protocol.
There are two privacy settings in MSN Messenger:
The client is expected to use this value in deciding how to behave when someone is added the RL who hasn't previously been put on the AL or BL. It's possible, for example, for someone to have been on your RL once before, then removed, then come back on, in which case they might already be on your block or allow list. The default setting is
People who are on neither your
The only time you can receive the phone numbers that you have set for yourself is during a
Here is a list of the five different phone number types in the order that they are sent:
Phone numbers are not sent if they are empty,
The value for the first three items can be anything up to 95 characters. This value can contain any characters allowed in a nickname and is URL-encoded.
The value of
There are reports of a sixth phone number type to handle MSN Direct devices. This
Below is an example of the phone numbers of someone who has set her home phone number and has a mobile device but has chosen not to allow people to page her on MSN. Note that the home phone number is URL-encoded, and would show up like this when decoded: "555 555-0690".
After sending the
If the person is in your FL, you will also receive some
It is also possible to receive
The third parameter is the principal's "list number", which represents the lists they're in (allow, block, forward, reverse). Each list has a numerical value - the forward list is 1, the allow list is 2, the block list is 4 and the reverse list is 8. A principal's list number represents the sum of the lists the principal is in. For example, someone on your forward and allow lists but not your block or reverse lists would have a list number of 3.
Because list values are all powers of 2, you can tell which lists a principal is in with the bitwise AND function. ANDing the principal's list number with the value of a list will tell you whether they are in that list. For example, if a principal's list number is 3, "3 AND 1" returns "1" (meaning that they're on your forward list), "3 AND 2" returns "2" (meaning they're on your allow list), while "3 AND 4" and "3 AND 8" return "0" (meaning they aren't on your block or reverse lists).
Everyone on your reverse list should be on either your allow or block list, but this isn't always the case (for example, if they were added since you last logged off). You can check this by ANDing their list number with 14 (the sum of the add, block and allow lists). If the result is "8", they're on your reverse list but neither of the others. For example, if a buddy's list number is "11", "11 AND 14" returns "10" (meaning they have already been added to your allow list); whereas if their list number is "9", "9 AND 14" returns "8" (meaning they haven't been added to your add or block lists). See GTC above for how to handle these people.
There are some programs that erase everyone from your allow list so that you can appear offline to people while you talk, but when you log back on again with a normal client, they are often flooded with messages about new buddies.