msnp-wiki/docs/files/notification.md

# Introduction
`<NOTIFICATION>` documents are the basis behind the [NOT](../commands/not.md) and [IPG](../commands/ipg.md) commands.
Being such, it was introduced with [MSNP5](../versions/msnp5.md).

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>`](#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>`](#to) element.
* `notification_id`: The `id` attribute from [`<NOTIFICATION>`](#notification) element.
* `message_id`: The `id` attribute from [`<MSG>`](#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>`](#to) element.
* `notification_id`: The `id` attribute from [`<NOTIFICATION>`](#notification) element.
* `message_id`: The `id` attribute from [`<MSG>`](#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](../versions/msnp9.md)) 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>`](#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](../versions/msnp9.md) and higher.

The [`<TEXT>`](#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>`](#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>`](#body) element entirely,
replacing all of it's children.
This sub-document is XML encoded if set as the inner data of the [`<BODY>`](#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](../services/abservice.md).

## CID
Contains only the Common ID of the user associated with this notification.

This element is exclusive to notifications generated by the [Address Book Service](../services/abservice.md).

## 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 Common ID.
Added since [MSNP13](../versions/msnp13.md).

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.