Convention on mailbox notifications for Nokia-provided connection managers
==========================================================================

Introduction
------------

This convention was created in order to implement client-side support
for handling service mailbox notifications. The benefit from using a common
set of headers is in minimisation of inconsistency between the different ways
of presenting and handling stored messages in a service mailbox,
such as recorded voicemail messages. 

Receiving mailbox notifications
---------------------------------
Mailbox notifications come as incoming messages through a channel of type Text
supporting the Messages interface, with special headers present so that
the notification UI can filter them as special events, similar to how it's done
to delivery reports.

The headers useful for generalized voicemail notifications should be:

'message-type': Channel_Text_Message_Type
    Must be set to Channel_Text_Message_Type_Notice for mailbox notifications.
    The clients, however, should not regard this value to determine
    if the message is a notification; they should rely on
    the header ``x-nokia-mailbox-notification`` instead. The reason for this
    is, the Telepathy specification may add a dedicated type value for
    mailbox notifications in the future.

'x-nokia-mailbox-notification': s
    If present, classifies the message as belonging to this convention.
    The recognized values are:
    * 'voice' - for voicemails
    * 'video' - for video messages
    * 'fax' - incoming faxes
    * 'email' - incoming email

'x-nokia-mailbox-has-unread': b
    Whether the mailbox had unread messages at the time of this notification,
    if applicable.
    Must not be set on one-per-event notifications such as those received
    for Skype voicemail.

'x-nokia-mailbox-unread-count': u
    Number of unread mailbox messages at the time of this notification,
    if known.
    Must not be set on one-per-event notifications such as those received
    for Skype voicemail.

'message-sender': Handle
    The contact handle of the mailbox service number, if applicable. The
    semantic of this is, a number to call in order to interact with mailbox
    messages (as opposed to calling back the caller who left the message).

'x-nokia-voicemail-type': s
    Both SMS and Skype voicemail notifications (x-nokia-mailbox-notification
    with value "voice") with must have this header.
    The recognized values are 'skype' for Skype notifications,
    and 'tel' for SMS notifications.
    **Note:** Same information could be obtained from the Telepathy account or
    other secondary information sources, but for purposes of voicemail
    handling, this header should be the primary way of distinguishing
    voicemail of different types.  

'x-nokia-mailbox-discard-text: b
    If true, this message should not be shown as a text message to the user.
    The text contents of the message (if any) are intended only for
    graceful interworking with clients not supporting the conventions
    described in this document.

The following headers apply only to notifications that are received per stored
event, as opposed to mailbox state summaries:

'x-nokia-mail-sender': Handle
    The contact handle of the stored message's sender, if known.

'message-sent': Unix_Timestamp64
    If present, contains the UNIX timestamp of the time when the stored message
    has been recorded.

'message-subject': s
    **Tentative, pending approval in the Telepathy specification**
    Optional text subject.

'x-nokia-voicemail-duration': u
    Duration of the voicemail message in seconds, if known.

The message can also have a body or attachments (i.e. Message_Part list items
beyond the first one containing the message headers), which can be used in
presenting the notification to the user.

Listening to voicemail
----------------------
Unfortunately, the Telepathy usage has to differ here, because of the different
ways of selecting voicemail messages to listen (telephony has none;
Skype lets you search by contact name and timestamp).

For SMS notifications, a regular call to the handle indicated in
'message-sender' should be established.

For Skype notifications, a call channel should be requested from the Skype
connection, with a null target handle and requested properties of interface
``com.nokia.Telepathy.Channel.Interface.Voicemail.Skype``:

VoicemailSender: Handle
    The handle from the header 'x-nokia-mail-sender' of the notification.
VoicemailTimestamp: Unix_Timestamp64
    The timestamp from the header 'message-sent' of the notification.

The call channel should have one audio stream with receive-only direction.
Pending adoption of InitialAudio call property should be considered for
blending into.

Recording a voicemail greeting
------------------------------
Our requirements do not demand this feature; a similar extended call property
convention can be used in the future.
