There are two ways to connect to a switchboard: you can either request a new switchboard session or be invited to an existing one. Both of these events take place on the notification server. When connecting to the switchboard, a client will need to handle the creation of a session (XFR) and being invited (RNG) somewhat differently.

Requesting a Switchboard Session

Notification Server

To request a switchboard session, the client must send the XFR command to the NS with a TrID and a parameter of SB (for switchboard). The server will reply with another XFR with instructions on authenticating with the switchboard. Below is an example:

>>> XFR 15 SB\r\n

<<< XFR 15 SB 207.46.108.37:1863 CKI 17262740.1050826919.32308\r\n

The first parameter tells you that you are being transferred to a switchboard (this should always remain the same). Note that in the dispatch server, this parameter reads NS.
The second parameter is the colon-delimited string for the address and port (has always been 1863) of the switchboard server.
The third parameter specifies the type of authentication, which should always be CKI.
The fourth parameter is an authentication string that the client will need to send when connecting to the switchboard to prove its identity.

However, if you have not set your initial status, or you are set to HDN, you may not transfer to a switchboard. Instead of receiving an XFR in response to your XFR, you will receive error 913.

Switchboard Server

The client must now initiate a TCP connection to the given switchboard IP on the given port (without closing the NS connection). The connection details are as explained in the Connections page. The client can wait at least two minutes and still connect to the switchboard safely.

Once connected to the switchboard, the client must send the USR command. It must have a TrID, your account name as the first parameter, and the authentication string as the second parameter. This command must be sent within approximately one minute or else the switchboard will close the connection.

If successful, the server will respond with a USR with the same TrID, OK as the first parameter, your account name as the second parameter, and your display name as the third parameter.

If of either (or both) the account name or the authentication string were incorrect, the server will send error 911 and close the connection.
If the format was wrong, the server will immediately close the connection with no error.
If you try to authenticate with the correct information with the wrong switchboard server (different IP), you will be disconnected with no error.
If you have already logged into the switchboard server with the authentication information, and try to log in again with the same information, you will receive error error 911 and be disconnected. Note that you can still connect to multiple switchboards simultaneously, but you must send multiple XFRs and use each one separately.

Below is an example of logging in correctly:

<o> Client Connects to 207.46.108.37 1863 (Switchboard)

>>> USR 1 example@passport.com 17262740.1050826919.32308\r\n

<<< USR 1 OK example@passport.com Example%20Name\r\n

<o> Continue SB Session . . .

Below is an example of logging with the wrong authentication string:

<o> Client Connects to 207.46.108.37 1863 (Switchboard)

>>> USR 1 example@passport.com 17262740.1050826919.32307\r\n

<<< 911 1\r\n

<o> Switchboard Closes Connection

Now that you are properly authenticated with a switchboard server, you may invite principals as described in the Participants page.

Getting Invited to a Switchboard Session

Notification Server

When a principal invites you to a switchboard session, you will receive an RNG command over the notification server. The official client will automatically connect to a switchboard session and won't open a chat window until a plaintext message is sent, but third party clients may choose to behave differently.

The RNG command has no TrID and five parameters:

The first parameter is the session ID of the new switchboard session. Every switchboard session has a unique ID, and each principal invited will use the same session ID. You will need this for authenticating with the switchboard.
The second parameter is the colon-delimited string for the address and port (has always been 1863) of the switchboard.
The third parameter specifies the type of authentication, which should always be CKI.
The fourth parameter is an authentication string that you will need when authenticating with the switchboard.
The fifth and sixth parameters are respectively the account name and the URL-encoded display name of the principal that invited you to the switchboard session.

Here is an example RNG command:

<<< RNG 11752013 207.46.108.38:1863 CKI 849102291.520491113 example@passport.com Example%20Name\r\n

The client does not respond to this command. Instead, it opens a new connection to the IP and port given in the second parameter.

Switchboard Server

As with XFR, you should open a TCP connection to the server within two minutes of receiving the RNG command. The first thing you must send is the ANS command. The ANS command has a TrID and three parameters. The first parameter is your account name, the second parameter is the authentication string, and the third parameter is the switchboard session ID.

If successful, the server will respond with one or more IROs followed by an ANS. However, several things can go wrong.

If you connect but do not send ANS, the switchboard will close the connection with no error in about one minute.
If you don't connect within about one minute of receiving the RNG, the switchboard will close the connection with no error upon receiving the ANS.
No matter what, if your session ID is wrong, you will be disconnected with no error.
If you send a nonexistent or invalid account name and/or an incorrect authentication string, you will receive error 911 and the server will close the connection.
If the general syntax of the ANS is wrong, you will be disconnected with no error.
If you connect to the wrong switchboard address and try to authenticate, you will be disconnected with no error.
If you (or an attacker) has already connected and authenticated, and you authenticate with the correct information again, you will receive error 911 and the switchboard will close the connection.
If all of the participants in the switchboard session leave before you connect and send ANS, the switchboard session will be destroyed before you enter, and you will therefore be disconnected with no error after sending ANS.

The list of participants already in the switchboard session is sent with the IRO command, which probably stands for "initial roster". A separate IRO will be sent for each participant. Note that you, having just entered, are not included in this list. IRO has the same TrID as the ANS and four parameters.

The first parameter is the number of the current IRO command in the list. In the first IRO command, this will be 1, the second will be 2, and so on until the total number of commands.
The second parameter is the total number of IRO commands that will be sent.
The third parameter is the participant's account name.
The fourth parameter is a display name for the participant. If the participant has changed their display name since joining the switchboard session, this parameter will be out-of-date.

Because display names reported by the switchboard server can be out-of-date, you should use the display name given to you by the notification server if possible.

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 principals (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 . . .