Notification messages are used in MSN Messenger to notify you about a time-sensitive event, such as an incoming text message or a news item. Despite the name, it has nothing to do with the notification server. At present, it's used to receive notices from MSN Calendar and MSN Alerts, and to receive incoming messages from MSN Mobile. MSN Calendar became a fee-based service in May 2003, so our information about it is out of date.

A notification is a UTF-8 formatted XML document, so you may want to use a ready-made XML parsing library to process notifications. Some XML parsers are listed on the projects page. Unfortunately, some notifications are badly formatted - for example, URLs may contain bare & characters (which should be encoded as &) and unescaped http://s in the middle of URLs (which should be http%3a%2f%2f). We assume these are bugs in the program that generated the notifications, but you should be aware of them and program defensively.

Not all notices have quite the same format, so you can write a single complex routine to handle all of them or separate simple routines to handle each one. Most of the variations affect parts of the message which are no longer useful once the message has been delivered (e.g. an e-mail address to send the message to if the principal is offline), and it's entirely possible that Microsoft will make other variations in future. The official client seems to use a single complex function, and you're recommended to as well.

So far, it appears that MSN Calendar, MSN Alerts, and MSN Mobile each use a different notification format - but it's entirely possible that MSN Calendar now uses the same format as MSN Alerts, because the information we have about that service is out-of-date. The ver attribute in the NOTIFICATION element seems to identify the format of a notification document, but the official client doesn't pay attention to this attribute, so this shouldn't be relied upon.

Notification formats

I have written Document Type Definitions for the individual MSN Calendar, MSN Alerts, and MSN Mobile formats, as well as a general one. Additionally, here are examples of each notification format. Variable parts are coloured red:

MSN Calendar

<NOTIFICATION ver="1" siteid="111100200" siteurl="http://calendar.msn.com" id="1">\r\n <TO pid="0x00060000:0x81ee5a43" name="example@passport.com" />\r\n <MSG pri="" id="1">\r\n <ACTION url="/calendar/isapi.dll?request=action&operation=modify&objectID=1&uicode1=modifyreminder&locale=2052"/>\r\n <SUBSCR url="/calendar/isapi.dll?request=action&operation=modify&objectID=1&uicode1=modifyreminder&locale=2052"/><CAT id="111100201" />\r\n <BODY lang="2052" icon="/En/img/calendar.png">\r\n <TEXT>goto club 7. 2002 21:15 - 22:15 </TEXT>\r\n </BODY>\r\n </MSG>\r\n </NOTIFICATION>\r\n

The unusual features of this notification type are:

The ver attribute of the NOTIFICATION element is set to "1".
The email attribute of the TO element is missing
The VIA and FROM elements are missing.
The ACTION element comes before the SUBSCR element
There's a CAT element
The BODY element has an icon attribute.

MSN Alerts

<NOTIFICATION ver="2" id="1342902633" siteid="199999999" siteurl="http://alerts.msn.com">\r\n <TO pid="0x0006BFFD:0x8582C0FB" name="example@passport.com"/>\r\n <MSG pri="1" id="1342902633">\r\n <SUBSCR url="http://g.msn.com/3ALMSNTRACKING/199999999ToastChange?http://alerts.msn.com/Alerts/MyAlerts.aspx?strela=1"/>\r\n <ACTION url="http://g.msn.com/3ALMSNTRACKING/199999999ToastAction?http://alerts.msn.com/Alerts/MyAlerts.aspx?strela=1"/>\r\n <BODY lang="3076" icon="">\r\n <TEXT>utf8-encoded text</TEXT></BODY></MSG>\r\n </NOTIFICATION>\r\n

The unusual features of this notification type are:

The ver attribute of the NOTIFICATION element is set to "2"
The email attribute of the TO element is missing
The VIA and FROM elements are missing.
The SUBSCR element comes before the ACTION element
The CAT element is missing
The BODY element has an icon attribute.

MSN Mobile

<NOTIFICATION id="0" siteid="111100400" siteurl="http://mobile.msn.com/">\r\n <TO name="example@passport.com" pid="0x00037ffe:0x82f131c1" email="example@passport.com">\r\n <VIA agent="mobile"/>\r\n </TO>\r\n <FROM pid="0x00037ffe:0x82f131c1" name="example@passport.com"/>\r\n <MSG pri="1" id="0">\r\n <ACTION url="2wayIM.asp"/>\r\n <SUBSCR url="2wayIM.asp"/>\r\n <CAT id="110110001"/>\r\n <BODY lang="2057">\r\n <TEXT>Message </TEXT>\r\n <EMAILTEXT>The following mobile instant message could not be delivered to you via Messenger because you were offline.\r\n From: example@passport.com\r\n Message: Message </EMAILTEXT>\r\n </BODY>\r\n </MSG>\r\n </NOTIFICATION>\r\n

The unusual features of this notification type are:

The ver attribute of the NOTIFICATION element is missing.
The TO element has an email attribute.
There are VIA and FROM elements.
The ACTION element comes before the SUBSCR element
There's a CAT element
The icon attribute of the BODY element is missing.
There's an EMAILTEXT element

Explanation

We don't understand the purpose of some parts of the notification. Some parts are definitely not useful once the message has been delivered to the client (e.g. the TO element), so it may be that those parts we don't understand aren't useful either.

NOTIFICATION element

The NOTIFICATION element is the root element for notification documents.

The optional ver attribute is believed to identify the type of notification being used: it's missing in MSN Mobile, the value is 1 in MSN Calendar and the value is 2 in MSN Alerts.
The required id attribute is a number that uniquely identifies the notification being sent
The required siteid attribute is a number that uniquely identifies the website associated with the document
The required siteurl attribute is the URL of the website associated with the alert

TO element

The TO element specifies who the notification is being sent to.

The required pid attribute contains two values separated by colons: the values of MemberIdLow and MemberIdHigh from your initial profile
The required name attribute is your passport
The optional email attribute is (presumably) the e-mail address the alert will be sent to if you're offline

VIA element

The VIA element specifies the device this notification has been sent through. The (required) agent attribute has only been seen with a value of mobile, denoting a message sent through an MSN Mobile device.

FROM element

The FROM element specifies the principal that sent the notification.

The required pid attribute is identical to the pid attribute in the TO element, above
The required name attribute is the sender's passport

MSG element

The MSG element contains the message data.

the required pri attribute performs some unknown function
The required id attribute is a number that uniquely identifies the message. In practice, this is always identical to the id attribute in the NOTIFICATION element, above

ACTION element

The ACTION element contains part of the action URL (see below). The required url attribute is a relative or absolute URL. If it's a relative URL (i.e. it begins with "http://", "ftp://", "https://", etc.), you should add the siteurl attribute of the NOTIFICATION element to the front of this URL.

SUBSCR element

The SUBSCR element contains part of the subscription URL (see below). The required url attribute is a relative or absolute URL. If it's a relative URL (i.e. it begins with "http://", "ftp://", "https://", etc.), you should add the siteurl attribute of the NOTIFICATION element to the front of this URL.

CAT element

The CAT element performs some unknown function. The required id attribute is a number that performs some unknown function

BODY element

The BODY element contains the possible variants of the message that the principal could be sent.

the required lang attribute is a decimal number identifying the locale ID of the message text
the required icon attribute is a relative URL specifying an icon you might want to display alongside the message. It may be empty

TEXT and EMAILTEXT elements

These elements contain the actual message text to be sent. If the principal is on-line, the message in the TEXT element should be displayed. Otherwise, the message in the EMAILTEXT element will be sent to the address specified in the email attribute of the TO element.

How to use notifications

The product of a notification is a plaintext message, an action URL, a subscription URL, and (optionally) the sender's e-mail address. The "action" and "subscription" URLs are web addresses that the client should allow the user to visit. The action URL generally contains more information about the notification, while the subscription URL contains subscription options.

The TEXT element contains the message to be sent to the principal, and the name attribute of the FROM element contains the sender's e-mail address. The URLs are derived from several attributes.

Each URL is made up of the base URL derived from the SUBSCR or ACTION element, and the id attributes of the NOTIFICATION and MSG elements. The URL is made up by putting the values together like this: base_URL&notification_id=NOTIFICATION_id&message_id=MSG_id&agent=messenger.

For example, a site with a siteurl of http://mysite.com, an action URL of /script.asp, notification ID of 1, and a message ID of 2, the target URL would be http://mysite.com/script.asp&notification_id=1&message_id=2&agent=messenger.