Since March 10, 2003 - Version 2

MSN Messenger Protocol

Home Page






Validate XHTML
Validate CSS
Switchboard - Participants
Printable Version

Joining a Switchboard Session

If you are invited to a switchboard session, you will receive a list of participants in the session after successfully authenticating. If you initiated the switchboard session, you will never receive this list.

The list of participants is sent with the IRO command, probably standing for "initial roster". This is a list command and is therefore is very similar to that of the LSG command and the LST command. A separate IRO will be sent for each participant. Note that you, the user that was just invited, are not included in this list.

  • Each IRO shall contain the same TrID as the ANS you sent to authenticate with the switchboard.
  • The first and second parameters of the IRO command are the incrementing number and the total number respectively. The incrementing number starts at 1 for the first participant, and is equal to the total number for the last participant. The total number is the total number of participants in the session.
  • The third parameter is the participant's account name.
  • The fourth parameter is friendly name of the participant. However, if the participant changed his or her friendly since joining the switchboard session, this parameter will not be updated until the user leaves and rejoins the switchboard session.

After receiving the last IRO (where the incrementing number is the same as the total number), you will receive ANS with the same TrID as the ANS that you sent initially, with the parameter OK. After receiving this, you are officially part of the switchboard session and can send and receive messages.

Below is an example of authenticating with the switchboard and finding out that there are two other users (making a total of three):

<o> Client Connects to 1863 (Switchboard)

>>> ANS 1 849102291.520491113 11752013\r\n

<<< IRO 1 1 2 Mike\r\n

<<< IRO 1 2 2 My%20Name\r\n

<<< ANS 1 OK\r\n

<o> Continue SB Session . . .

Inviting Users

A user cannot enter a switchboard session without being invited by a current participant. Any participant, not just the creator of the session, can invite other users. There is no known limit on the number of users in a switchboard session, but it is most likely greater than 30. There used to be a limit of five.


To invite a user into a switchboard session, send the CAL command to the switchboard. It should have a TrID and the account name of the user you wish to invite as the first parameter.

If successful, the server will respond with another CAL with the same TrID, the string RINGING as the first parameter, and the session ID of this switchboard session as the second parameter. Note that this is only an acknowledgment that you invited the user - the user has not joined the session yet. That comes later with the JOI command. Also, the session ID is not important to the client, and it will be the same for every user invited.

There are several things that can go wrong with the CAL command:

  • If you try to invite a user that is already in the session (including yourself), you will receive error 215. This error will also be sent if you try to invite a user that has already been invited by your or another participant but has not yet joined.
  • If the format was incorrect (e.g. too few or too many parameters), you will be immediately disconnected from the switchboard. However, as with every other case with the switchboard, the NS is not informed of anything and therefore the connection to the NS remains open.
  • If the user is offline or account name specified is nonexistent (i.e. myname@hotmail), you will receive error 217 but will not be disconnected.
  • If the account name is invalid, such as @@a, you will receive error 208 and remain connected.
  • If the user that you are trying to invite is online and either blocking you, or has BLP set to AL and does not have you on his or her AL, you will receive error 216. This also does not disconnect you.

Below are some examples of using the CAL command:

>>> CAL 2\r\n

<<< CAL 2 RINGING 11752013\r\n

>>> CAL 3\r\n

<<< 217 3\r\n

>>> CAL 4\r\n

<<< 217 4\r\n

>>> CAL 5 @@a\r\n

<<< 208 5\r\n

>>> CAL 5\r\n

<<< 216 5\r\n

Only the person sending the CAL will see the outgoing CAL and the incoming CAL or errors. When the specified user actually joins the session, every user will receive a JOI.


If the CAL was successful, the specified user will receive the RNG command from the NS. If they connect to the switchboard and authenticate, they will be part of the switchboard session. When that happens, every user in the session (excluding the user that just joined) will be sent the JOI command.

The JOI command has no TrID. The first parameter is the account name of the user that just entered the session. The second parameter is the URL-encoded friendly name of the user that just entered the session. Below is an example:

<<< JOI Name_123\r\n

Leaving a Switchboard Session

To leave a switchboard session, a client should send the OUT command with no TrID and no parameters. The switchboard will then close the connection. However, you may also close the connection with no command, and the switchboard will remove you from the switchboard session as long as you closed the connection properly. Below is an example of using the OUT command.

>>> OUT\r\n

<o> Switchboard Closes Connection

When a participant leaves a switchboard session, all other users in the session (if there are any left) will receive the BYE command with no TrID and the account name of the user that left as the first parameter. Below is an example:

<<< BYE\r\n

Idle Sessions

If you are the only participant in a switchboard session (either because you haven't invited anyone yet or because everyone left), the switchboard will close the connection after five minutes of being alone. No command will be sent from the server before closing the connection.

If you are in a 2 person switchboard session, and no commands are sent from either user for five minutes, the switchboard will send the BYE command to both users showing that the other user left and it will immediately close the connection. However, this BYE command has an additional parameter after the account name that says 1, showing that the switchboard was closed due to idleness. Below is an example:

<<< BYE 1\r\n

<o> Switchboard Closes Connection

The situation in a 3 or more person session is similar to that in a 2 person session, except that the idle duration is 15 minutes and you will only receive one BYE for a random user in the session.

Official Client

Whenever someone using the official closes a message window, it will disconnect from the switchboard, unless the switchboard was already closed from being idle. The official client will tell you when a user leaves a switchboard with three or more participants, but it will not tell you in a switchboard with only 2 participants.

Relation to Notification Server

Because the integration between switchboard servers and the notification server is not very tight, a user can log off of the NS and still be connected to one or more switchboards. When the official client logs out of MSN Messenger, it will send OUT to every active switchboard and then send OUT to the NS.

Copyright ©2002-2003 to Mike Mintz.