The use of messages (MSG) is the only way to send information to other users in the switchboard session. Each message sent to a session is relayed to every other user 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 recognize 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.
To send a message to the switchboard, send the MSG command.
U, N, or A. If it is U, you will receive no acknowledgment. If it is N, you will receive acknowledgment only if the message was not properly received. If it is A, you will receive acknowledgment 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). Acknowledgment is explained below.MSG comes after the newline after the second parameter. 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.
Acknowledgment 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 acknowledgment 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 user that sent the message. The second parameter is the friendly name of that user (note that if the user changed his or her friendly 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.
There are three standard types of messages used by the official client: instant messages (text), typing notifications, and application invitations. Each type of message is differentiated by a unique Content-Type field in the header. Clients may send messages with nonstandard content types for special features such as encryption and feature negotiation. The official client ignores all messages with nonstandard content types, and therefore all clients should as well. In addition, the official client completely ignores malformed messages: e.g. a message without a MIME header.
Instant messages, also known as plaintext messages, are the regular messages sent back and forth on MSN. They are sent with either Content-Type: text/plain or Content-Type: text/plain; charset=UTF-8 (each specify a different message encoding). Because the explanation for this type of message is quite long, it is fully explained in the Plaintext page.
A typing notification is sent to inform the other participants in a switchboard session that you are currently typing a message.
Content-Type: text/x-msmsgscontrol. It must not include charset=UTF-8.TypingUser field in the header. Its value should be your account name.\r\n).Below is an example of a typing message (just the payload, not the MSG line):
MIME-Version: 1.0\r\n
Content-Type: text/x-msmsgscontrol\r\n
TypingUser: example@passport.com\r\n
\r\n
\r\n
TypingUser field, it may display that value instead of your friendly name for the user who is typing a message. Third party clients should just ignore the value of this field and use the source of the MSG to determine who is typing the message.Application invitations are used to invite users to join applications such as file transfer, voice conversation, video conferencing, NetMeeting, remote assistance, whiteboard, games, and more. Invitations use Content-Type: text/x-msmsgsinvite; charset=UTF-8 and the charset parameter is not optional. Because the explanation for this type of message is quite long, it is fully explained in the Invitations page.
There are several message types that are not used or understood by the official client. These message types were created by third party client developers. Many of the common unofficial message types are explained in the Unofficial Protocol page.