Since March 10, 2003 - Version 2.1
hypothetic.org

MSN Messenger Protocol

Client - Messages

Back To Normal Layout

Overview

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:

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:

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:

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.

TO element

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

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.

MSG element

The MSG element contains the message data.

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.

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.

Copyright ©2002-2004 to Mike Mintz.
<http://www.mikemintz.com/>