MSN Messenger Protocol
What are payload commands?
A payload command is a special type of command that spans multiple lines. The best way to think of these commands is as regular single-line commands followed by a payload with a specified number of bytes of binary data.
Unlike commands, payloads have no universal format. Their format is defined by the rules of each specific payload command. You cannot separate them from the regular command flow by trying to figure out where they end. You must read the number of bytes specified in the payload command and use it to parse the payload.
A payload command (not including the payload itself - just the first line) might or might not have a TrID (depending on the context). It can have any number of parameters following the TrID depending on the syntax of the specific command. After the last parameter (or the TrID if there are no parameters) comes a positive integer. This number represents the length of the payload in bytes. Certain commands have specific limits on the length of the payload.
After the payload length, the command always ends with a newline. As usual, this is treated as specified in the Commands page.
Right after the newline comes the payload itself. It will always be the specified length in bytes. After the payload, normal command flow resumes.
Sending payload commands is very easy. Most programming languages have some sort of len() function that will find the length of the string you are sending in bytes. Just use this number, but remember not to include the newline at the end of the actual payload command itself (before the payload).
Note that the server relies on the message length that you provide. If you say that you are going to send 88 bytes and you send 87, the server will wait until you send something else, and then interpret the first byte of the next command as the last byte of the payload. You will end up sending an invalid command to the server. Similar problems will occur if your message length is too short.
Receiving payload commands is much harder. You cannot rely on the entire command to be in one packet, or to end with a newline. 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.
Messages were the first and are arguably the most important payload command in the protocol. They are represented by the
When sending messages, you must include a TrID and one parameter specifying the acknowledgment you wish to receive from the server. You can only send message in an SB session, not in an NS session. More details about the syntax of outgoing messages are described in the Switchboard Messages page.
When sending messages, because the server does not interpret the payload, you can send anything you want in the payload, as long as it's not too long and the payload length parameter is correct. However, the payloads of messages are expected to be formatted in a particular way.
Much like in MIME, each message is divided into a header and a body. The header and body are separated by the first appearance of new newlines in a row.
The header of a message should be in the form of a standard MIME header as described in RFC 1521. The MIME header consists of an unordered list of fields separated by newlines. Each newline must be a
Every field has a key and a value, for example:
The key should be considered case-sensitive. Third party clients should always send field key names in the case provided in this documentation. The last character of a key must be a colon, and will be followed by a space. The key can't have a colon anywhere else in it, but the value can have several or none. For example, in file transfer, one client might send:
And the other client might come back with:
Additional parameters may be specified in any one field. Each parameter is separated by a semi-colon followed by a space, and each parameter should be a key/value pair separated by an equal sign. Below is an example of a field with five parameters:
Because fields are unordered, a client must be prepared to see them in any order, regardless of the fact that the official client always sends fields in the same order. Also, a client must be prepared to receive messages with unknown fields and should ignore these. For example, GAIM will include a field something like
Every valid message is required to have a
The body of the message can pretty much be anything. If the header of the message specifies that the body of the message is UTF-8 encoded, then the body should be UTF-8 encoded. Note that this does not affect the message length. You must calculate the message length based on the raw number of bytes, and not the number of "characters".
In regular text messages, the official client adds newlines with
It's possible for messages to have no body. If you just end a message with the two newlines at the end of the header, it will have an empty body.
Other Payload Commands
There are several other commands besides