msnp-wiki/docs/files/notification.md

Introduction

<NOTIFICATION> documents are the basis behind the NOT and IPG commands. Being such, it was introduced with MSNP5.

This article only describes the <NOTIFICATION> command from .NET Alerts 5.0 and below, and not the <Notify> element used in .NET Alerts 6.0 and above.

NOTIFICATION

This is the root element of the document, and supports four attributes:

• ver: This is always 1. Seems optional, or was removed later.
• id: A 32-bit unsigned integer that is set by the sending party.
• siteid: The .NET Alerts Site ID, not to be confused with the .NET Passport Site ID. Setting this to some values changes the default icon:
  • 0: Use stocks (stack of coins or line-chart) icon
  • 1: Use calendar (clock) icon
  • Other values: Use default bell icon or custom icon
• siteurl: The base URL to the service used in later relative URL attributes.

TO

This element supports two attributes:

• pid: The recipient's Passport Unique ID. The format for the PUID is 0xHHHHHHHH:0xLLLLLLLL, where H is the hexadecimal representation of the profile's MemberIdHigh variable, and where L is the hexadecimal representation of the profile's MemberIdLow variable.
• name: The recipient's display name or user handle. Optional.

If this element (<TO>) does not have a (<VIA>) element, it is to be empty.

VIA

NOTE: This element seems to only exist as backwards compatibility from .NET Alerts 6.0.

This empty element only supports one attribute:

• agent: What this alert is intended to be viewed by:
  • email: A e-mail message.
  • messenger: A "toast" generated by the Official Client.
  • mobile: A mobile device.

FROM

NOTE: This element should NOT be added to any <NOTIFICATION> documents.

This optional empty element supports two attributes:

• pid: The sender's Passport Unique ID. Follows the same format as <TO>'s pid parameter.
• from: The sender's display name or user handle. Optional.

MSG

This is the primary element of the document, and supports two attributes:

• pri: This is always empty, and should NOT be set. May be set to 1 for incoming pages. Optional.
• id: The notification's numeric ID, defaulting to '0', and should NOT be changed.

ACTION

This element supports only one attribute:

• url: The main URL that is used when this notification is activated, relative to siteurl.

When opened by a client, the following are added to the URL as query parameters:

• to_pid: The pid attribute from <TO> element.
• notification_id: The id attribute from <NOTIFICATION> element.
• message_id: The id attribute from <MSG> element.
• agent: The client that activated this notification. The Official Client sets this to messenger. Optional.

SUBSCR

This element supports only one attribute:

• url: The configuration URL that is used when the notification's change option is activated, relative to siteurl.

When opened by a client, the following are added to the URL as query parameters:

• to_pid: The pid attribute from <TO> element.
• notification_id: The id attribute from <NOTIFICATION> element.
• message_id: The id attribute from <MSG> element.
• agent: The client that activated this notification. The Official Client sets this to messenger. Optional.

CAT

NOTE: This element is obsolete and should NOT be added to any <NOTIFICATION> documents.

This optional empty element only supports one attribute:

• id: The category ID of this notification.

BODY

This is the main body of the document, and supports two attributes:

• lang: The decimal LCID that this notification document is meant to display in. Optional, but should be set.
• icon: The custom 32x32 PNG icon URL, relative to siteurl. Optional. Note: Client Version 6.0 (MSNP9) and above support 48x32 icons and will use them automatically if your icon URL includes the substring _32x32, the client will replace it with _48x32. If you do not have a 48x32 icon, the client will fallback to the original 32x32 icon.

The default element that this parents is <TEXT>. It may also contain other types of data. One such data type is the <NotificationData> sub-document.

This element (including the <BODY> and </BODY>) are restricted in size to 1024 bytes.

NAME

NOTE: This element should NOT be added to any <NOTIFICATION> documents.

This optional element contains the friendly name of the recipient.

TEXT

This optional element contains the text data of the notification.

TEXTX

This optional element contains the extended text data of the notification, supported by MSNP9 and higher.

The <TEXT> element is required for this to be parsed by the Official Client.

The inner document of this is required to be XML encoded.

P

A paragraph, required for <TEXTX> elements to parse correctly.

This element supports one attribute:

• align: The extended notification's text alignment:
  • left
  • center
  • right

This element may contain any of the following elements:

• P: Nested paragraph, also supporting the align element.
• B: Bold text.
• I: Italic text.
• BR: This empty element denotes a line-break.

NotificationData

This element may instead be contained in the <BODY> element entirely, replacing all of it's children. This sub-document is XML encoded if set as the inner data of the <BODY> element.

This element supports two attributes:

• xmlns:xsd: is always set to http://www.w3.org/2001/XMLSchema
• xmlns:xsi: is always set to http://www.w3.org/2001/XMLSchema-instance

Service

Contains only ABCHInternal. Unknown if there are other values supported.

This element is exclusive to notifications generated by the Address Book Service.

CID

Contains only the Contact ID of the user associated with this notification.

This element is exclusive to notifications generated by the Address Book Service.

SpaceHandle

This element only has one child named ResourceID.

This element and it's children are exclusive to notifications generated by the blog service.

ResourceID

Contains the blog service's ID for this user.

ComponentHandle

This element only has one child named ResourceID.

This element and it's children are exclusive to notifications generated by the blog service.

ResourceID

Contains the blog service's ID for the main component.

OwnerCID

This element only contains a signed 64-bit integer for the Contact ID. Added since MSNP13.

This element and it's children are exclusive to notifications generated by the blog service.

LastModifiedDate

Contains a ISO 8601-compatible timestamp with 7 millisecond digits.

This element is omitted in notifications generated by the persistant group service.

Action

Only observed to contain Add. Unknown if there are other values supported.

This element is exclusive to notifications generated by the blog service.

HasNewItem

Contains either true or false.

ComponentSummary

This element has two children named <Component> and <Items>.

This element and it's children are exclusive to notifications generated by the blog service.

Component

This element has one child named ResourceID and supports one attribute:

• xsi:type: The type of this <Component>:
  • List: A list.
  • Folder: A photo collection.
  • MessageContainer: A text message container.

ResourceID

Contains the blog service's ID for this <Component>.

Items

This element supports multiple <Item> child elements.

Item

This element has one child named ResourceID and supports one attribute:

• xsi:type: The type of this <Component>:
  • ListEntry: An entry on a list.
  • Photo: A photo.
  • Message: A text message.

ResourceID

Contains the blog service's ID for this <Item>.

CircleId

Contains the GUID of the persistant group.

This element is exclusive to notifications generated by the persistant group service.