Plaintext messages, also known as instant messages, are the regular messages sent between users on MSN. Sending a plaintext message instructs clients receiving the message to display it on-screen, optionally with some simple formatting.
Plaintext messages sent with Content-Type: text/plain
are treated as ISO 8859-1 encoded messages. Plaintext messages sent with Content-Type: text/plain; charset=UTF-8
are treated as UTF-8 encoded messages. If you create a new content-type with a another charset value (e.g. charset=iso-8859-15
), the official client will not display the message. ISO-8859-1 and UTF-8 encodings are discussed in the Connections page.
The X-MMS-IM-Format
field was introduced in MSN Messenger 2.0. This field specifies formatting options for the content of the message such as font name and color. This field is optional, and if it is omitted, it will interpreted by the receiving client to have default formatting options (whatever the client decides). Clients that do not support formatting (like MSN Messenger 1.0) should ignore this field and display the message as if the field was not there. Because this field consists of many parameters, it will be explained below.
The body of a plaintext message is the content of the message with no changes. There are no special fields in the body - the only change that a client might have to make is encoding the body in UTF-8 if specified in the Content-Type
field.
To manually separate lines in the content of a message or add blank lines, just add more \r\n
s. However, the official client ignores all \n
s in the body of a message, so it is legal to separate lines with just \r
s.
Emoticons may be included in the body of a plaintext message. Emoticons are expressed in their text form. For example, to send a smiley face, the body would contain :)
. No special codes are required. A list of common emoticons and their textual counterparts are listed on this MSN Help page.
Below is an example message with two lines and UTF-8 encoding specified.
MIME-Version: 1.0
\r\n
Content-Type: text/plain; charset=UTF-8\r\n
X-MMS-IM-Format: FN=Arial; EF=I; CO=ff0000; CS=0; PF=22\r\n
\r\n
Hello!\r
How are you?
Below is an example message with two lines in ISO 8895-1 with no formatting options and an emoticon.
MIME-Version: 1.0
\r\n
Content-Type: text/plain\r\n
\r\n
I'm fine. :)\r\n
And you?
The value of the X-MMS-IM-Format
field is a list of parameters. It can include any number of the parameters in any order, but if FN
is included, it must be the first parameter. If it is not, the switchboard will close the connection and not send the message. Presumably, this is because of the measures Microsoft took to prevent malicious users from taking advantage of the font name bug in the official client. Because server software constantly changes, third party clients should expect incoming messages to have FN
in any order.
The official client always sends these fields in this given order: FN
, EF
, CO
, CS
, PF
. The RL
parameter is included at the end if right-justification is used, otherwise it is not included. The official client will accept parameters in any order.
The official client always sends uppercase parameter names. Results are unpredictable when sending lowercase or mixed-case parameter names to the official client, but third party clients should still expect names to be in any case.
Note that it is impossible to specify font sizes. A client is expected to determine the size of the font in all messages based on user preferences.
The FN
parameter specifies a font name. The font name must be URL-encoded. For example, to have a font of "MS Sans Serif", you would have to specify FN=MS%20Sans%20Serif
. Font names are not case sensitive, and only spaces should be URL-encoded. URL-encoding other characters such as numbers and letters cause unpredictable results. If the receiving client does not have the specified font, it should make judgment based on the PF
and CS
parameters. Basically, the client should select whichever available font supports the character set specified in CS
and is closest to the category specified in PF
. If those parameters are not present, the client should just use a default font.
There used to be a bug in the official client that caused it to crash upon receiving a message with a font that contained many %20
s. To prevent this from happening, MSN patched the switchboard server so that it would close the connection if a user attempts to do this.
The EF
parameter specifies optional style effects. Possible effects are bold, italic, underline, and strikethrough. Each effect is referred to by its first letter. For example, to make bold-italic text, include the parameter EF=IB
or EF=BI
. The order does not matter. Any unknown effects are to be ignored. The official client always sends effects in uppercase, and the results are unpredictable when it receives lowercase effects. If there are no effects, just leave the parameter value blank.
The CO
parameter specifies a font color. Many versions of the official client limit you to sending only a few select font colors, but it is possible to specify any one of almost 17 million colors (24-bit color). The value of the CO
field is a six-character hexadecimal BGR (blue-green-red, the reverse of the standard RGB order seen in HTML) string. The first two characters represent a hexadecimal number from 00
ff
(hexadecimal for 255) for the intensity of blue, the second two are for green, and the third two are for red. For example, to make a full red color, send CO=0000ff
.
The official client always sends lowercase hexadecimal letters, but it will accept uppercase letters just the same. The official client also cuts off all leading zeros in outgoing messages. For example, 0000ff
could be expressed as ff
, but both are valid. Black may be expressed as simply 0
. Other variations such as 7-character strings or unusual characters cause unpredictable results.
If you are used to dealing with colors in HTML, just omit the hash sign and reverse the order of the colors. If you are not used to expressing colors in hexadecimal like this, you might find this tutorial useful, but realize that MSN expresses colors in the order of blue-green-red and can omit leading zeros.
The term "character set" is quite ambiguous. The charset=UTF-8
in the Content-Type
field has a completely different meaning to the CS
parameter in the X-MMS-IM-Format
field.
"Character set", as used in the X-MMS-IM-Format
field, refers to the set of characters which a font must know how to translate into squiggles ("glyphs") on the screen. It's used mostly in the Windows world, and is increasingly a legacy from the time before Unicode was well supported. A font must support at least one character set, but may support more than one - for example, "Wingdings" supports the Symbol character set, "Verdana" supports the Western, Greek, Turkish, Central European, and Cyrillic character sets. Some background information on character sets is available on this MSDN page.
Character sets are identified in the CS
parameter with one or two hexadecimal digits (leading zeros are dropped by the official client and are ignored if present), representing the numerical value Windows uses for the character set. Here is the full list of Windows' predefined character sets:
0
- ANSI_CHARSET
1
- DEFAULT_CHARSET
2
- SYMBOL_CHARSET
4d
- MAC_CHARSETLT
80
- SHIFTJIS_CHARSET
81
- HANGEUL_CHARSET
82
- JOHAB_CHARSET
86
- GB2312_CHARSET
88
- CHINESEBIG5_CHARSET
a1
- GREEK_CHARSET
a2
- TURKISH_CHARSET
a3
- VIETNAMESE_CHARSET
b1
- HEBREW_CHARSET
b2
- ARABIC_CHARSET
ba
- BALTIC_CHARSET
cc
- RUSSIAN_CHARSET_DEFAULT
de
- THAI_CHARSET
ee
- EASTEUROPE_CHARSET
ff
- OEM_DEFAULT
You should not assume that clients receiving your messages will understand all character sets (for example, Windows NT 3.51 has very poor character set support). MSN Messenger only allows you to specify a single character set in a CS
field. This charset is arbitrary, but it is advisable to make it the one which will cause the most characters to be displayed correctly. The official client just offers the user a list of character sets supported by your chosen font.
The PF
family defines the category that the font specified in the FN
parameter falls into. This parameter is used by the receiving client if it does not have the specified font installed. The value is a two-digit hexadecimal number. When programming with Windows APIs, this value is the PitchAndFamily value in RichEdit and LOGFONT.
The first digit of the value represents the font family. Below is a list of numbers for the first digit and the font families they represent. This list was adapted from this MSDN page.
0_
- FF_DONTCARE
1_
- FF_ROMAN
2_
- FF_SWISS
3_
- FF_MODERN
4_
- FF_SCRIPT
5_
- FF_DECORATIVE
The second digit represents the pitch of the font - in other words, whether it is monospace or variable-width.
_0
- DEFAULT_PITCH
_1
- FIXED_PITCH
_2
- VARIABLE_PITCH
Below are some PF values and example fonts that fit the category.
12
22
31
42
The RL
parameter specifies whether a message should be right-justified or not. It's value is 1
if the message is right-justified. The official client always omits this parameter unless the value is 1
, but any other value does nothing and keeps the message left-justified. This parameter is useful for languages which are written from right to left, such as Arabic and Hebrew, and is automatically sent by the official client with any message using such a language.
X-MMS-IM-Format: FN=MS%20Sans%20Serif; EF=; CO=0; CS=0; PF=22
X-MMS-IM-Format
field expresses the MS Sans Serif font with no effects and a black color.
X-MMS-IM-Format: FN=Comic%20Sans%20MS; EF=S; CO=800000; CS=0; PF=42
X-MMS-IM-Format: FN=Verdana; CO=ff; EF=UB; PF=22; CS=cc
FN
is in the front, it's all right.
X-MMS-IM-Format: FN=Courier%20New; EF=; CO=ff00ff; CS=0; PF=31
X-MMS-IM-Format: FN=My%20Hebrew%20Font; EF=; CS=b1; PF=00; RL=1