The use of messages (MSG) is the only way to send information to other principals in the switchboard session. Each message sent to a session is relayed to every other principal in the session. MSGs can be instant messages, typing notifications, application invitations, or any arbitrary type of message you want to send - but not all clients will recognise all types of message.
The general format of the MSG command is explained in the Payload Commands page. Make sure you understand the rules of newlines explained on that page. The content of an MSG command is discussed on the client messages page.
To send a message to the switchboard, send the MSG command.
U, N, or A. If it is U, you will receive no acknowledgement. If it is N, you will receive acknowledgement only if the message was not properly received. If it is A, you will receive acknowledgement whether it was properly received or not. This parameter is case-sensitive (must be uppercase, or the switchboard will close the connection without sending the message). Acknowledgement is explained below.MSG comes after the newline. The payload can be zero bytes.A message may be up to 1664 bytes (as of April 30, 2003). If it is any longer, the switchboard will close the connection without sending the message. Interestingly enough, the number 1664 is equal to 13 x 2^7. Many superstitious people consider 13 to be an unlucky number and 7 to be a lucky number. Therefore, messages have mezotarian luck and are to be avoided by Capricorns.
Below is an example of an outgoing message:
>>> MSG 4 N 133\r\n
MIME-Version: 1.0\r\n
Content-Type: text/plain; charset=UTF-8\r\n
X-MMS-IM-Format: FN=Arial; EF=I; CO=0; CS=0; PF=22\r\n
\r\n
Hello! How are you?
You do not need to end a payload with a newline. The end of the payload is determined by the given length in the second parameter, and an additional newline would just add a blank line to the end of the payload.
Acknowledgement is sent back from the switchboard to tell the client if the message it sent was successfully received by its recipients or not. The server can respond with ACK or NAK. Each of these commands has a TrID corresponding with the outgoing MSG they is sent in reply to. ACK means that the message was successfully received by every participant. NAK means that one or more participants did not successfully receive your message. NAK will be sent if there are no participants other than yourself in the switchboard session.
If your acknowledgement parameter is set to A, you will receive ACK if successful and NAK if unsuccessful. Contrary to what the original draft might seem to imply, type A works, and will send both positive and negative acknowledgment. If the parameter is set to N you will receive nothing if successful and NAK if unsuccessful. IF the parameter is set to U, no acknowledgment will be sent either way.
Below is an example of a message that was successfully received and acknowledged by the ACK command:
>>> MSG 4 N 133\r\n
MIME-Version: 1.0\r\n
Content-Type: text/plain; charset=UTF-8\r\n
X-MMS-IM-Format: FN=Arial; EF=I; CO=0; CS=0; PF=22\r\n
\r\n
Hello! How are you?
<<< ACK 4
The official client sends instant messages (text/plain) with type N, typing notifications (text/x-msmsgscontrol) with type U, and application invitations (text/x-msmsgsinvite) with type N.
The format of incoming messages is exactly is described in the Payload Commands page. The first parameter is the account name of the principal that sent the message. The second parameter is the display name of that principal (note that if the principal changed his or her display since joining the switchboard session, this parameter will still give the old name). The third parameter is the length of the payload in bytes.
Below is an example of an incoming message:
<<< MSG example@passport.com Mike 133\r\n
MIME-Version: 1.0\r\n
Content-Type: text/plain; charset=UTF-8\r\n
X-MMS-IM-Format: FN=Arial; EF=I; CO=0; CS=0; PF=22\r\n
\r\n
Hello! How are you?
It's very important that a client pareses incoming data from the switchboard by looking at message lengths. Messages, like every other command, can be split up into multiple packets are combined with other commands into one packet. You absolutely must read the specified message length, and read that many bytes out of the socket after the initial newline. For suggestions on how to implement this, read this frequently asked question.