Since March 10, 2003 - Version 2
hypothetic.org

MSN Messenger Protocol

Switchboard - Participants

Back To Normal Layout

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.

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 207.46.108.38 1863 (Switchboard)

>>> ANS 1 name_123@hotmail.com 849102291.520491113 11752013\r\n

<<< IRO 1 1 2 example@passport.com Mike\r\n

<<< IRO 1 2 2 myname@msn.com 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.

CAL

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:

Below are some examples of using the CAL command:

>>> CAL 2 name_123@hotmail.com\r\n

<<< CAL 2 RINGING 11752013\r\n

>>> CAL 3 nonexistent@passport.com\r\n

<<< 217 3\r\n

>>> CAL 4 offline@passport.com\r\n

<<< 217 4\r\n

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

<<< 208 5\r\n

>>> CAL 5 blocking_you@passport.com\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.

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@hotmail.com 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 example@passport.com\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 example@passport.com 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.
<http://www.mikemintz.com/>