Abstract

This specification defines a System Level API which offers a simple interface to get access to mobile messaging services. A typical use case of the Messaging API is the implementation of a messaging client application that allows the user to send SMS and MMS messages as well as to access and manage the received SMS and MMS messages.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was produced by the System Applications Working Group. Members of this Working Group have agreed not to progress the Messaging API specification further as a Recommendation track document, electing instead to publish it as an informative Working Group Note under a permissive license with a view to enabling it to form the basis of further work by others, e.g. in a W3C Community Group.

This document was published by the System Applications Working Group as a Working Group Note. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All comments are welcome.

W3C makes this document available under the terms of the W3C Software and Document License pursuant to W3C's policy for Relicensing Unfinished W3C Specifications. Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

The Messaging API provides operations to get access to the primitives offered by mobile messaging services (send, receive) as well as those that allow to manage a mobile messaging client inbox (delete, store, mark as read)

An example of use is provided below:

Example 1
navigator.messaging.sms.send ( '+1234567890', 'How are you?').then(
  function(message) { window.console.log('Message with identifier  ' +
                      message.messageID + ' sent at ' + message.timestamp); },
  function(error) {   window.console.error('Error: ' + error); } )

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, SHALL, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fire an event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in ECMAScript 6 (ECMA-262).

4. Security and privacy considerations

This API must be only exposed to trusted content

6. MessagingManager Interface

The MessagingManager interface represents the initial entry point for getting access to the mobile messaging services, i.e. SMS and MMS.

interface MessagingManager {
    readonly    attribute SmsManager sms;
    readonly    attribute MmsManager mms;
    Promise findMessages (MessagingFilter filter, FilterOptions options);
    Promise findConversations (DOMString groupBy, MessagingFilter filter, FilterOptions options);
    Promise getMessage (DOMString messageID);
    Promise deleteMessage (DOMString messageID);
    Promise deleteConversation (DOMString conversationID);
    Promise markMessageRead (DOMString messageID, boolean value, optional boolean sendReadReport = false);
    Promise markConversationRead (DOMString conversationID, boolean value, optional boolean sendReadReport = false);
};

6.1 Attributes

sms of type SmsManager, readonly
Provides access to the SMS service's specific functionality.
mms of type MmsManager, readonly
Provides access to the MMS service's specific functionality.

6.2 Methods

findMessages
This method makes a request to retrieve the messages matching the filter described by the filter parameter and according to the filtering options described in the options. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a MessagingCursor to access the set of messages.
ParameterTypeNullableOptionalDescription
filterMessagingFilter Filter that identifies the set of messages that are requested to be retrieved
optionsFilterOptions Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results).
Return type: Promise
findConversations
This method makes a request to retrieve the list of conversations in which the messages can be grouped using the criteria defined by the groupBy parameter. Only those messages matching the filter described in the filter parameter SHALL be included in the resulting conversations, what can be useful for instance to filter just a specific type of messages (e.g. SMS) or to implement message search in a conversational messaging client. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a MessagingCursor to access the set of conversations.
ParameterTypeNullableOptionalDescription
groupByDOMString Indicates the criteria used to define the conversations. It may have the values 'participants' if a conversation is to be defined as the set of messages exchanged among the same set of parties, and 'subject' if a conversation is to be defined as the set of messages with the same subject.
filterMessagingFilter Filter that identifies the set of messages that are requested to be included in the resulting conversations.
optionsFilterOptions Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results) to be aplied when filtering the messages to be included in each of the resulting conversations.
Return type: Promise
getMessage
This method makes a request to retrieve the message identified by the messageID parameter. It returns a new Promise object which allows the caller to be notified about the result of the operation.
ParameterTypeNullableOptionalDescription
messageIDDOMString Identifier of the message that is requested to be retrieved
Return type: Promise
deleteMessage
This method requests the deletion of the message with identifier equal to the messageID parameter. A new Promise is returned in order to notify the request result (success or error) to the caller.
ParameterTypeNullableOptionalDescription
messageIDDOMString Identifier of the message that is requested to be deleted
Return type: Promise
deleteConversation
This method requests the deletion of all the messages in the conversation with identifier equal to the conversationID parameter. A new Promise is returned in order to notify the request result (success or error) to the caller.
ParameterTypeNullableOptionalDescription
conversationIDDOMString Identifier of the conversation whose messages are requested to be deleted
Return type: Promise
markMessageRead
This method requests to mark as read or unread the message with identifier equal to the messageID parameter. The method returns a new Promise that will allow the caller to be notified about the result (success, error) of the operation.
ParameterTypeNullableOptionalDescription
messageIDDOMString Identifier of the message that is requested to be marked as read or unread
valueboolean Indicates whether the message is to be marked as read ('true') or unread ('false')
sendReadReportboolean = false Indicates that, in case a Read Report was requested, it is to be sent ('true') or not ('false', which is the default)
Return type: Promise
markConversationRead
This method requests to mark as read or unread all the messages in the conversation with identifier equal to the conversationID parameter. The method returns a new Promise that will allow the caller to be notified about the result (success, error) of the operation.
ParameterTypeNullableOptionalDescription
conversationIDDOMString Identifier of the conversation whose messages are requested to be marked as read or unread
valueboolean Indicates whether the messages in the conversation are to be marked as read ('true') or unread ('false')
sendReadReportboolean = false Indicates that, in case a Read Report was requested for any MMS message in the conversation, a Read Report is to be sent ('true') or not ('false', which is the default)
Return type: Promise

6.3 Steps

The findMessages method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to get the message(s) matching the filter included in the filter parameter and according to the filtering options described in the options parameter.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let messagingCursor be a new MessagingCursor object providing access to the results of the retrieval, i.e. the set of SmsMessage and/or MmsMessage elements.
    2. Invoke resolver's fulfill algorithm with messagingCursor as the value argument.

The findConversations method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to get the set of conversations in which the messages can be grouped, according to the set of participants or the subject as indicated in the groupBy parameter, and filtering the messages included in those conversations according to the filter included in the filter parameter and the filtering options described in the options parameter.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let messagingCursor be a new MessagingCursor object providing access to the results of the retrieval, i.e. the set of Conversation elements.
    2. Invoke resolver's fulfill algorithm with messagingCursor as the value argument.

The getMessage method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to get the message with identifier equal to the messageID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let message be the SmsMessage or MmsMessage whose identifier matches the messageID parameter.
    2. Invoke resolver's fulfill algorithm with message as the value argument.

The deleteMessage method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete the message with identifier equal to the messageID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let messageID be the messageID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with messageID as the value argument.

The deleteConversation method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete the messages in the conversation with identifier equal to the conversationID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let conversationID be the conversationID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with conversationID as the value argument.

The markMessageRead method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to mark as read/unread (depending on the value parameter being respectively 'true' or 'false') the message with identifier equal to the messageID parameter passed in the request, and to send a Read Report if sendReadReport is set to 'true'.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let messageID be the messageID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with messageID as the value argument.

The markConversationRead method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to mark as read/unread (depending on the value parameter being respectively 'true' or 'false') the messages in the conversation with identifier equal to the conversationID parameter passed in the request, and in case sendReadReport is set to 'true', to send a Read Report for each of the MMS messages for which it was requested.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let conversationID be the conversationID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with conversationID as the value argument.
Note
It is FFS whether the methods deleteMessage() and markMessageRead() should also accept an array of message identifiers as input parameter.

7. SmsManager Interface

The SmsManager interface represents the SMS messaging service manager.

interface SmsManager : EventTarget {
    readonly    attribute MessageType  type;
    readonly    attribute DOMString[]  serviceIDs;
    Promise segmentInfo (DOMString text, optional DOMString serviceID);
    Promise send (DOMString to, DOMString text, optional DOMString serviceID);
    Promise clear (DOMString serviceID);
                attribute EventHandler onreceived;
                attribute EventHandler onsent;
                attribute EventHandler ondeliverysuccess;
                attribute EventHandler ondeliveryerror;
                attribute EventHandler onserviceadded;
                attribute EventHandler onserviceremoved;
};

7.1 Attributes

type of type MessageType, readonly
MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
serviceIDs of type array of DOMString, readonly
MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
onreceived of type EventHandler,
Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
onsent of type EventHandler,
Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
ondeliverysuccess of type EventHandler,
Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
ondeliveryerror of type EventHandler,
Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
onserviceadded of type EventHandler,
Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
onserviceremoved of type EventHandler,
Handles the serviceremoved event of type ServiceChangeEvent, fired when an existing messaging service is disabled on this messaging service manager.

7.2 Methods

segmentInfo
This method issues a request to get information on the number of concatenated SMS segments needed to send the text in the text parameter, the number of characters available per segment and the maximum number of available characters in the last segment. A Promise object will be returned in order to notify the result of the request.
ParameterTypeNullableOptionalDescription
textDOMString Text intended to be sent as an SMS, whose segmentation information is checked by this method.
serviceIDDOMString Identifier of the service through which the message is would be sent.
Return type: Promise
send
This method issues a request to the messaging system to send an SMS message with the text of the text parameter to the destination number indicated in the to parameter. A Promise object will be returned in order to notify the result of the request.
ParameterTypeNullableOptionalDescription
toDOMString Destination number for the SMS message.
textDOMString Content of the SMS message to be sent.
serviceIDDOMString Identifier of the service through which the message is requested to be sent.
Return type: Promise
clear
This method makes a request to delete all the messages associated to the messaging service passed as parameter.
ParameterTypeNullableOptionalDescription
serviceIDDOMString Identifies the messaging service all whose messages are requested to be deleted.
Return type: Promise

7.3 Steps

The send method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Let smsMessage be a new instance of SmsMessage:
    1. Generate a identifier for this message that is globally unique within the implementation, i.e. there cannot be any other message with the same identifier.
    2. Set the messageID of smsMessage to the generated identifier.
    3. Set the type of smsMessage to 'sms'.
    4. Set the serviceID of smsMessage to the identifier of the service used to send the message, i.e. the one passed in the serviceID parameter, if provided, or otherwise to the first item in the serviceIDs attribute of the SmsManager.
    5. Set the from of smsMessage to the number of the mobile subscription used to send this SMS message.
    6. Set the read of smsMessage to 'true'.
    7. Set the to of smsMessage to the value of the to parameter.
    8. Set the body of smsMessage to the value of the text parameter.
    9. Set the messageClass of smsMessage to 'class1'.
    10. Set the state of smsMessage to 'sending'.
    11. Set the deliveryStatus of smsMessage to 'pending' if a delivery report has been requested or to 'not-applicable' otherwise.
    12. Make a request to the system to send an SMS message with text passed in the text parameter to the number of the recipient indicated in the to parameter, using the proper service as described above.
    13. Queue a task to monitor SMS submission process.
  4. If an error occurs run these substeps and terminate these steps
    1. If a delivery report had been requested set the deliveryStatus of smsMessage to 'error'.
    2. invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Set the state of smsMessage to 'sent'.
    2. Set the timestamp of smsMessage to the device's date when the SMS message was sent, i.e. when the SMS-SUBMIT Protocol Data Unit was sent.
    3. Invoke resolver's fulfill algorithm with smsMessage as the value argument.
    4. Queue a task to fire an event named sent with the message attribute set to smsMessage.

The segmentInfo method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Let smsSegmentInfo be a new instance of SmsSegmentInfo.
  4. Make a request to the system to calculate the segmentation information related to the sending as SMS the text passed in the text parameter, using the service with identifier equal to the one passed in the serviceID parameter, if provided, or otherwise to the first item in the serviceIDs attribute of the SmsManager.
  5. Queue a task to monitor the calculation process.
  6. If an error occurs run these substeps and terminate these steps
    1. invoke resolver's reject algorithm with error as the value argument.
  7. When the request has been successfully completed:
    1. Set the segments of smsSegmentInfo to the number of concatenated SMS segments needed to send the provided text.
    2. Set the charsPerSegment of smsSegmentInfo to the number of characters available per SMS segment. This number depends on the encoding to be used to send the SMS message, which in turn depends on the language / special characters included in the text.
    3. Set the charsAvailableInLastSegment of smsSegmentInfo to the maximum number of available characters in the last segment that would be needed to send the input string. This provides useful information to the user on the number of characters that can type without requiring an additional SMS segment to send the text.
    4. Invoke resolver's fulfill algorithm with smsSegmentInfo as the value argument.

Note that the application that has invoked the segmentInfo method SHOULD NOT split the text in a set of strings that fit each into a single SMS segment and send each of them by an independent call to the sendSMS method as it would result in different independent SMS messages being sent, but SHOULD instead send the full message in a single sendSMS request. However having information on the number of SMS segments may be required by the application in order to inform the user (e.g. in case the length of the text impacts on the price charged for sending the message).

Upon a new SMS message being received, the user agent MUST:

  1. Let smsMessage be a new instance of SmsMessage.
  2. Generate a identifier for this message that is globally unique within the implementation, i.e. there cannot be any other message with the same identifier.
  3. Set the messageID of smsMessage to the generated identifier.
  4. Set the type of smsMessage to 'sms'.
  5. Set the serviceID of smsMessage to the identifier of the service at which the message has been received.
  6. Set the from of smsMessage to the sender of the SMS message, i.e. the value of the TP Originating Address (TP-OA) field of the SMS message [GSM-SMS].
  7. Set the timestamp of smsMessage to the timestamp of the SMS message, i.e. the value of the TP-Service-Centre-Time-Stamp (TP-SCTS) parameter received in the SMS DELIVER Protocol Data Unit [GSM-SMS].
  8. Set the read of smsMessage to 'false'.
  9. Set the to of smsMessage to the recipient of the SMS message, i.e. the value of the TP Destination Address (TP-DA) field of the SMS message [GSM-SMS].
  10. Set the messageClass of smsMessage to the message class indicated in the TP-Data-Coding-Scheme (TP-DCS) field of the SMS message [GSM-SMS].
  11. Set the body element to the text of the received SMS message, i.e. the value of the SM element contained within the TP User Data (TP-UD) field of the SMS message [GSM-SMS].
  12. Set the state of smsMessage to 'received'.
  13. Set the deliveryStatus of smsMessage to 'not-applicable'.
  14. Queue a task to fire an event named received with the message attribute set to smsMessage.
  15. Queue a task to fire a system message named received of type ReceivedMessage with the message attribute set to smsMessage.

Upon a delivery report of a previously sent SMS message being received, the user agent MUST

  1. Let smsMessage be the instance of SmsMessage to which this delivery report is related.
  2. Set the deliveryStatus parameter of smsMessage to 'success' or 'error' depending on the reported result.
  3. Set the deliveryTimestamp of smsMessage to the delivery time of the SMS message, i.e. the TP-Discharge-Time (TP DT) parameter included in the SMS-STATUS-REPORT Protocol Data Unit [GSM-SMS].
  4. Queue a task to fire an event named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
    1. the messageID attribute set to the messageID attribute of smsMessage,
    2. the serviceID attribute set to the serviceID attribute of smsMessage,
    3. the first item in the recipients attribute set to the to attribute of smsMessage, and
    4. the first item in the deliveryTimestamps attribute set to delivery time of such message.
  5. Queue a task to fire a system message of type DeliveryReportnamed deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
    1. the messageID attribute set to the messageID attribute of smsMessage,
    2. the serviceID attribute set to the serviceID attribute of smsMessage, and
    3. the first item in the recipients attribute set to the to attribute of smsMessage.
    4. the first item in the deliveryTimestamps attribute set to delivery time of such message.

The clear method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let serviceID be the serviceID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with serviceID as the value argument.

7.4 Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the SmsManager object.

event handler event name event type short description
onreceived received MessagingEvent handles received messages
onsent sent MessagingEvent handles sent messages
ondeliverysuccess deliverysuccess DeliveryReportEvent handles successful delivery reports
ondeliveryerror deliveryerror DeliveryReportEvent handles failure delivery reports
onserviceadded serviceadded ServiceChangeEvent handle new messaging services
onserviceremoved serviceremoved ServiceChangeEvent handle disabled messaging services

8. SmsSegmentInfo Dictionary

The SmsSegmentInfo dictionary contains information about the segmentation of a given text to be sent as SMS.

dictionary SmsSegmentInfo {
             long segments;
             long charsPerSegment;
             long charsAvailableInLastSegment;
};

8.1 Dictionary SmsSegmentInfo Members

segments of type long,
MUST return the total number of SMS segments needed to send the input string, taking into account the encoding to be used to send such message as well as the overhead associated to concatenated SMS messages.
charsPerSegment of type long,
MUST return the number of characters available per SMS segment as per the encoding to be used to send the SMS message. In case the variable length encoding, the value of this element MUST be calculated asumming the minimum length for all the characters.
charsAvailableInLastSegment of type long,
MUST return the maximum number of available characters in the last segment needed to send the input string. In case the variable length encoding, the value of this element MUST be calculated asumming the minimum length for all the remaining characters.

9. MmsManager Interface

The MmsManager interface represents the MMS messaging service manager.

interface MmsManager : EventTarget {
    readonly    attribute MessageType  type;
    readonly    attribute DOMString[]  serviceIDs;
    FetchMode getFetchMode (optional DOMString serviceID);
    void      setFetchMode (FetchMode fetchMode, optional DOMString serviceID);
    Promise   send (MmsContent mmsContent, optional MmsSendParameters sendParameters);
    Promise   fetch (DOMString messageID);
    Promise   clear (DOMString serviceID);
                attribute EventHandler onreceived;
                attribute EventHandler onsent;
                attribute EventHandler ondeliverysuccess;
                attribute EventHandler ondeliveryerror;
                attribute EventHandler onreadsuccess;
                attribute EventHandler onreaderror;
                attribute EventHandler onserviceadded;
                attribute EventHandler onserviceremoved;
};

9.1 Attributes

type of type MessageType, readonly
MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
serviceIDs of type array of DOMString, readonly
MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
onreceived of type EventHandler,
Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
onsent of type EventHandler,
Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
ondeliverysuccess of type EventHandler,
Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
ondeliveryerror of type EventHandler,
Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
onreadsuccess of type EventHandler,
Handles the readsuccess event of type ReadReportEvent, fired when a new succesful read report is received on this messaging service manager.
onreaderror of type EventHandler,
Handles the readerror event of type ReadReportEvent, fired when a new failure read report is received on this messaging service manager.
onserviceadded of type EventHandler,
Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
onserviceremoved of type EventHandler,
Handles the serviceremoved event of type ServiceChangeEvent, fired when an existing messaging service is disabled on this messaging service manager.

9.2 Methods

getFetchMode
This method requests to retrieve the fetch mode associated to a specific service (the one identified by the serviceID parameter, if provided, or the first item in the serviceIDs attribute of the MmsManager otherwise).
ParameterTypeNullableOptionalDescription
serviceIDDOMString Identifier of the service whose fetch mode is queried.
Return type: FetchMode
setFetchMode
This method issues a request to the messaging system to set the MMS message fetch mode for the service identified by the serviceID parameter, if provided, or for all services otherwise, to the mode indicated in the fetchMode parameter.
ParameterTypeNullableOptionalDescription
fetchModeFetchMode Fetch mode that is requested to be set for a specific service.
serviceIDDOMString Identifier of the service whose fetch mode is requested to be set.
Return type: void
send
This method issues a request to the messaging system to send an MMS message with the content and recipients included in the mmsContent parameter. A Promise object will be returned in order to notify the result of the request.
ParameterTypeNullableOptionalDescription
mmsContentMmsContent Content and recipients of the MMS message to be sent.
sendParametersMmsSendParameters Set of parameters related to the submission of the message (e.g. request of delivery/read report or not).
Return type: Promise
fetch
This method requests to fetch an MMS message with identifier equal to the indicated in the messageID parameter from the URL indicated in the MMS notification. The method returns a new Promise that will allow the caller to be notified about the result (success, error) of the operation.
ParameterTypeNullableOptionalDescription
messageIDDOMString Identifier of the MMS message that is requested to be download.
Return type: Promise
clear
This method makes a request to delete all the messages associated to the messaging service passed as parameter.
ParameterTypeNullableOptionalDescription
serviceIDDOMString Identifies the messaging service all whose messages are requested to be deleted.
Return type: Promise
Note
It is FFS whether MMS settings (e.g. fetch mode, creation mode) needs to be managed through the MmsManager interface.

9.3 Steps

The send method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Let mmsMessage be a new instance of MmsMessage and:
    1. Generate a identifier for this message that is globally unique within the implementation, i.e. there cannot be any other message with the same identifier.
    2. Set the messageID of mmsMessage to the generated identifier.
    3. Set the type of mmsMessage to 'mms'.
    4. Set the serviceID of mmsMessage to the identifier of the service used to send the message, i.e. the one passed in the serviceID parameter in MmsSendParameters, if provided, or otherwise to the first item in the serviceIDs attribute of the MmsManager.
    5. Set the from of mmsMessage to the number of the mobile subscription used to send this MMS message.
    6. Set the read of mmsMessage to 'true'.
    7. Set the to of mmsMessage to the to in the mmsContent parameter.
    8. Set the cc of mmsMessage to the cc array in the mmsContent parameter.
    9. Set the bcc of mmsMessage to the bcc array in the mmsContent parameter.
    10. Set the subject of mmsMessage to the value of the the subject parameter in mmsContent.
    11. Set the smil of mmsMessage to the value of the the smil parameter in mmsContent.
    12. Set the attachments of mmsMessage to the value of the the attachments array in mmsContent parameter.
    13. Set the state of mmsMessage to 'sending'.
    14. Add a new item in the deliveryInfo attribute of mmsMessage for each unique recipient included in the to, cc and bcc parameters (i.e. a single item if the same address has multiple ocurrences across these parameters), with the recipient attribute set to this recipient's address, with the deliveryStatus attribute set to 'pending', if a delivery report has been requested, or 'not-applicable' otherwise and with the readStatus attribute set to 'pending', if a read report has been requested, or 'not-applicable' otherwise.
    15. Make a request to the system to send an MMS message with the content passed in the content parameter to the number(s) of indicated in the to parameter, using the proper service as described above and asking for delivery and/or read report if requested.
    16. Queue a task to monitor MMS sending progress.
  4. If an error occurs run these substeps and terminate these steps
    1. If a delivery report had been requested set the deliveryStatus attribute of the different items in the deliveryInfo array attribute of mmsMessage to 'error'.
    2. invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Set the state of mmsMessage to 'sent'.
    2. Set the timestamp of mmsMessage to the device's date when the MMS message was sent, i.e. the date when the M-Send.req Protocol Data Unit was sent by the MMS Client.
    3. Invoke resolver's fulfill algorithm with mmsMessage as the value argument.
    4. Queue a task to fire an event named sent with the message attribute set to mmsMessage.

The reception of an MMS message is a two-step process: Firstly, an MMS notification encapsulated in a WAP Push OTA message [OMA-PUSH] is received by the device. This MMS notification contains limited information about the MMS message and a URL where the device can retrieve the full MMS message from. Secondly, the MMS message is retrieved either automatically, i.e. performed right after the reception of the MMS notification, or manually, i.e. invoked manually by the user.

Upon a new MMS notification being received, the user agent MUST:

  1. Let mmsMessage be a new instance of MmsMessage.
  2. Generate a identifier for this message that is globally unique within the implementation, i.e. there cannot be any other message with the same identifier.
  3. Set the messageID of mmsMessage to the generated identifier.
  4. Set the type of mmsMessage to 'mms'.
  5. Set the serviceID of mmsMessage to the identifier of the service at which the message has been received.
  6. Set the read of mmsMessage to 'false'.
  7. if the fetch mode is manual, never or the device is not in the home network and the the fetch mode is automatic-home:
    1. Set the from of mmsMessage to the value of the 'From' field of the MMS notification, if present.
    2. Set the timestamp of mmsMessage to the timestamp of the binary SMS message used to transport the MMS notification, i.e. the value of the TP-Service-Centre-Time-Stamp (TP-SCTS) parameter received in the SMS-DELIVER Protocol Data Unit [GSM-SMS].
    3. Set the expiry of mmsMessage to the value of the 'X-Mms-Expiry' field of the MMS notification.
    4. Add a new item in the to array of mmsMessage for each of recipients in the 'To' field of the MMS notification [MMS13], if present.
    5. Add a new item in the cc array of mmsMessage for each of recipients in the 'Cc' field of the MMS notification [MMS13], if present.
    6. Add a new item in the bcc array of mmsMessage for each of recipients in the 'Bcc' field of the MMS notification [MMS13], if present.
    7. Set the subject attribute to the value of the 'Subject' field of the MMS notification [MMS13], if present.
    8. Set the state of mmsMessage to 'not-downloaded'.
  8. if the fetch mode is otherwise automatic or the device is in the home network and the the fetch mode is automatic-home:
    1. Make a request to the system to fetch the MMS message from the URL indicated in the X-Mms-Content-Location field of the MMS notification. Once the MMS has been fetched continue with following steps.
    2. Run the steps for filling the MmsMessage object with the data contained in the MMS message enclosed in the M-Retrieve.conf Protocol Data Unit.
      1. Set the from of mmsMessage to the value of the 'From' field of the MMS message [MMS13].
      2. Set the timestamp of mmsMessage to the value of the 'Date' field of the MMS message [MMS13].
      3. Add a new item in the to array of mmsMessage for each of recipients in the 'To' field of the MMS message [MMS13], if present.
      4. Add a new item in the cc array of mmsMessage for each of recipients in the 'Cc' field of the MMS message [MMS13], if present.
      5. Add a new item in the bcc array of mmsMessage for each of recipients in the 'Bcc' field of the MMS message [MMS13], if present.
      6. Set the subject attribute to the value of the 'Subject' field of the MMS message [MMS13], if present.
      7. Set the smil attribute to a DOMString containing the SMIL object of the received MMS message [MMS13], if present.
      8. For each of the media files attached to the received MMS message add a new item to the attachments array with:
        1. A new Blob object including the actual content of the attachment and the media type. The charset encoding is indicated as part of the type attribute of the Blob object by means of appending a charset parameter after the media type as explained in [RFC2046], e.g. "text/plain; charset=utf-8".
        2. The contentID attribute filled with the Content-ID used to reference this attachment from the SMIL object in the incoming MMS message [MMS13], if present.
        3. The contentLocation attribute filled with the Content-Location used to reference this attachment from the SMIL object in the incoming MMS message [MMS13], if present.
      9. Set the readReportRequested attribute to 'true' if the 'X-Mms-Read-Report' field is present in the incoming MMS message [MMS13] and has the value 'Yes', and to 'false' otherwise.
    3. Set the state of mmsMessage to 'received'.
    4. Add a new item in the deliveryInfo array attribute of mmsMessage for each unique recipient included in the 'To', 'Cc' and 'Bcc' fields (i.e. a single item if the same address has multiple ocurrences across these parameters), with the recipient attribute set to this recipient's address and the deliveryStatus attribute set to 'not-applicable'.
  9. Queue a task to fire an event named received with the message attribute set to mmsMessage.
  10. Queue a task to fire a system message named received of type ReceivedMessage with the message attribute set to mmsMessage.

The fetch method can be invoked to fetch an MMS message that has not been automatically fetched upon receiving the corresponding MMS notification, e.g. due to the fetch mode being manual. When this method is invoked the User Agent MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. If the messageID parameter passed in the request matches with an MMS message that has already been fetched, or to an SMS message go to next step, otherwise let mmsMessage the message with messageID attribute equal to the messageID parameter and set the state of mmsMessage to 'fetching' and make a request to the system to fetch the MMS message.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Run the steps for filling the MmsMessage object with the data contained in the MMS message.
    2. Invoke resolver's fulfill algorithm with mmsMessage as the value argument.

An example of manual fetch of an MMS is provided below:

Example 2
navigator.setMessageHandler ('received', onMessageReceived)
function onMessageReceived(message) {
  if (message.type == 'sms') { window.console.log('SMS Message from ' +
                               message.from + ' received');  } 
  else if (message.type == 'mms') {
	window.console.log('MMS Message from ' + message.from + ' received');  
	if (message.state == 'not-downloaded') { 
		 window.console.log('MMS Message download started');  
		 navigator.messaging.mms.fetch (message.id).done(
			function(message) { window.console.log('MMS Message downloaded!');},
			function(error)   { window.console.error('Error: ' + error);} );
	}
  }
}
Note
It is FFS how to report the progress of the sending and fetching of an MMS message.

Upon a delivery report of a previously sent MMS message being received, the user agent MUST

  1. Let mmsMessage be the instance of MmsMessage to which this delivery report is related.
  2. For each of the items in the deliveryInfo array attribute of mmsMessage whose recipient attribute matches one of the recipients of the MMS to which the delivery report is related,
    1. set its deliveryStatus attribute:
      1. to 'success', in case of successful delivery, i.e. if the value of the X-Mms-Status element in the M-Delivery.ind Protocol Data Unit [MMS13] is 'Retrieved', or
      2. to 'error', in case of failed delivery, i.e. if the value of the X-Mms-Status element in the M-Delivery.ind Protocol Data Unit [MMS13] is 'Expired', 'Rejected' or 'Unreachable'.
    2. set its deliveryTimestamp attribute to the delivery time, i.e. the 'Date' field in the M-Delivery.ind Protocol Data Unit [MMS13], in case of successful delivery.
  3. Queue a task to fire an event named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
    1. the messageID attribute set to the messageID attribute of mmsMessage,
    2. the serviceID attribute set to the serviceID attribute of mmsMessage,
    3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this delivery report is related, and
    4. in case of successful delivery, with each of the items in the deliveryTimestamps attribute set to the delivery time of the MMS message to the corresponding recipient, i.e. that in the same position of the recipients array.
  4. Queue a task to fire a system message of type DeliveryReport named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
    1. the messageID attribute set to the messageID attribute of mmsMessage,
    2. the serviceID attribute set to the serviceID attribute of mmsMessage,
    3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this delivery report is related, and
    4. in case of successful delivery, with each of the items in the deliveryTimestamps attribute set to the delivery time of the MMS message to the corresponding recipient, i.e. that in the same position of the recipients array.

Upon a read report of a previously sent MMS message being received, the user agent MUST

  1. Let mmsMessage be the instance of MmsMessage to which this read report is related.
  2. For each of the items in the deliveryInfo array attribute of mmsMessage whose recipient attribute matches one of the recipients of the MMS to which the read report is related,
    1. set its readStatus attribute:
      1. to 'success', in case the message has been read, i.e. if the value of the X-Mms-Read-Status element in the M-Read-Orig.ind Protocol Data Unit [MMS13] is 'Read', or
      2. to 'error', in case the message has been deleted without being read, i.e. if the value of the X-Mms-Status element in the M-Read-Orig.ind Protocol Data Unit [MMS13] is 'Deleted without being read'.
    2. set its readTimestamp attribute to the read time, i.e. the 'Date' field in the M-Read-Orig.ind Protocol Data Unit [MMS13], in case the message has been read.
  3. Queue a task to fire an event named readsuccess or readerror respectively if the message has been read or not, with
    1. the messageID attribute set to the messageID attribute of mmsMessage,
    2. the serviceID attribute set to the serviceID attribute of mmsMessage,
    3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this read report is related, and
    4. in case the message has been read, with each of the items in the readTimestamps attribute set to the read time of the MMS message by the corresponding recipient, i.e. that in the same position of the recipients array.
  4. Queue a task to fire a system message of type ReadReport named readsuccess or readerror respectively if the message has been read or not, with
    1. the messageID attribute set to the messageID attribute of mmsMessage,
    2. the serviceID attribute set to the serviceID attribute of mmsMessage,
    3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this read report is related, and
    4. in case the message has been read, with each of the items in the readTimestamps attribute set to the read time of the MMS message by the corresponding recipient, i.e. that in the same position of the recipients array.

The clear method when invoked MUST run the following steps:

  1. Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
  2. Let promise be a new Promise object and resolver its associated resolver
  3. Return promise to the caller.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. When the request has been successfully completed:
    1. Let serviceID be the serviceID parameter passed in the request
    2. Invoke resolver's fulfill algorithm with serviceID as the value argument.

9.4 Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the MmsManager object.

event handler event name event type short description
onreceived received MessagingEvent handles received messages
onsent sent MessagingEvent handles sent messages
ondeliverysuccess deliverysuccess DeliveryReportEvent handles successful delivery reports
ondeliveryerror deliveryerror DeliveryReportEvent handles failure delivery reports
onreadsuccess readsuccess ReadReportEvent handles successful read reports
onreaderror readerror ReadReportEvent handles failure read reports
onserviceadded serviceadded ServiceChangeEvent handle new messaging services
onserviceremoved serviceremoved ServiceChangeEvent handle disabled messaging services

10. MmsSendParameters Dictionary

dictionary MmsSendParameters {
             optional DOMString serviceID;
             boolean            requestDeliveryReport;
             boolean            requestReadReport;
};

10.1 Dictionary MmsSendParameters Members

serviceID of type optional DOMString,
Identifier of the service through which the message is requested to be sent.
requestDeliveryReport of type boolean,
Flag to indicate whether a delivery report is requested.
requestReadReport of type boolean,
Flag to indicate whether a read report is requested.

11. SmsMessage Interface

The SmsMessage interface represents an SMS message as defined in [GSM-SMS]. This interface is not intended to represent binary SMS, which are out of the scope of this API.

interface SmsMessage {
    readonly    attribute DOMString      messageID;
    readonly    attribute MessageType    type;
    readonly    attribute DOMString      serviceID;
    readonly    attribute DOMString      from;
    readonly    attribute Date           timestamp;
    readonly    attribute boolean        read;
    readonly    attribute DOMString      to;
    readonly    attribute DOMString      body;
    readonly    attribute SmsState       state;
    readonly    attribute DeliveryStatus deliveryStatus;
    readonly    attribute Date?          deliveryTimestamp;
    readonly    attribute MessageClass   messageClass;
};

11.1 Attributes

messageID of type DOMString, readonly
MUST return the identifier of the message.
type of type MessageType, readonly
MUST return the type of message, i.e. 'sms'.
serviceID of type DOMString, readonly
MUST return the messaging service id used to send / receive this message.
from of type DOMString, readonly
MUST return the sender of the message, i.e. the TP Originating Address (TP-OA) of the SMS message.
timestamp of type Date, readonly
MUST return, for received messages the time the message reached the Short Message Center, indicated in the TP-Service-Centre-Time-Stamp (TP-SCTS) parameter of the SMS message, and for sent messages the the device's date when the SMS message was sent, i.e. when the SMS-SUBMIT Protocol Data Unit was sent.
read of type boolean, readonly
MUST return 'true' if the message has been marked as read, or 'false' otherwise.
to of type DOMString, readonly
MUST return the recipient of the message, i.e. the TP Destination Address (TP-DA) of the SMS message.
body of type DOMString, readonly
MUST return text of the SMS message, i.e. the SM element contained within the TP User Data (TP-UD) field of the SMS message.
state of type SmsState, readonly
MUST return the status of the SMS message.
deliveryStatus of type DeliveryStatus, readonly
MUST return the delivery status of the SMS message.
deliveryTimestamp of type Date, readonly , nullable
MUST return for sent messages the delivery date as reported in the TP-Discharge-Time (TP DT) parameter included in the SMS-STATUS-REPORT Protocol Data Unit or null if there is no positive knowledge about the delivery of the message. MUST return null for received messages.
messageClass of type MessageClass, readonly
MUST return the SMS message class, according to the value indicated in the TP-Data-Coding-Scheme (TP-DCS) field of the SMS.

12. MmsMessage Interface

The MmsMessage interface represents an MMS message, as defined in [MMS13].

interface MmsMessage {
    readonly    attribute DOMString         messageID;
    readonly    attribute MessageType       type;
    readonly    attribute DOMString         serviceID;
    readonly    attribute DOMString         from;
    readonly    attribute Date              timestamp;
    readonly    attribute unsigned long?    expiry;
    readonly    attribute boolean           read;
    readonly    attribute DOMString[]       to;
    readonly    attribute DOMString[]       cc;
    readonly    attribute DOMString[]       bcc;
    readonly    attribute DOMString         subject;
    readonly    attribute DOMString         smil;
    readonly    attribute MmsAttachment[]?  attachments;
    readonly    attribute MmsState          state;
    readonly    attribute MmsDeliveryInfo[] deliveryInfo;
    readonly    attribute boolean?          readReportRequested;
};

12.1 Attributes

messageID of type DOMString, readonly
MUST return the identifier of the message.
type of type MessageType, readonly
MUST return the type of message, i.e. 'mms'.
serviceID of type DOMString, readonly
MUST return the messaging service id used to send / receive this message.
from of type DOMString, readonly
MUST return the sender of the message, i.e. the 'From' field of the MMS message.
timestamp of type Date, readonly
MUST return, for received messages the time the message reached the Multimedia Messaging Service Center, i.e. the 'Date' field of the MMS message, for received but not downloaded messages the timestamp of the binary SMS message used to transport the MMS notification and for sent messages the device's date when the MMS message was sent, i.e. the date when the M-Send.req Protocol Data Unit was sent by the MMS Client.
expiry of type unsigned long, readonly , nullable
MUST return the number of seconds the message will be stored in the Multimedia Messaging Service Center and thus available for download. This time is calculated since the date the MMS Notification was sent.
read of type boolean, readonly
MUST return 'true' if the message has been marked as read, or 'false' otherwise.
to of type array of DOMString, readonly
MUST return an array containing the recipient(s) included in the 'To' field of the MMS message.
cc of type array of DOMString, readonly
MUST return an array containing the recipient(s) included in the 'Cc' field of the MMS message.
bcc of type array of DOMString, readonly
MUST return an array containing the recipient(s) included in the 'Bcc' field of the MMS message.
subject of type DOMString, readonly
MUST return the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
smil of type DOMString, readonly
MUST return the SMIL, i.e. the presentation element, unparsed as DOMString, that the messaging client needs to use to determine the way the content of the MMS message is displayed.
attachments of type array of MmsAttachment, readonly , nullable
MUST return the set of attachments of the MMS message.
state of type MmsState, readonly
MUST return the status of the MMS message.
deliveryInfo of type array of MmsDeliveryInfo, readonly
MUST return an array with each of the items indicating the delivery status and, if applicable, the delivery time to each of the recipients of the message.
readReportRequested of type boolean, readonly , nullable
MUST return true in case the originator of a received message requested a read report and false otherwise. MUST return null for sent messages.

13. MmsContent Dictionary

dictionary MmsContent {
             DOMString       subject;
             DOMString[]     to;
             DOMString[]     cc;
             DOMString[]     bcc;
             DOMString       smil;
             MmsAttachment[] attachments;
};

13.1 Dictionary MmsContent Members

subject of type DOMString,
Indicates the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
to of type array of DOMString,
Indicates the recipient(s) included in the 'To' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
cc of type array of DOMString,
Indicates the recipient(s) included in the 'Cc' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
bcc of type array of DOMString,
Indicates the recipient(s) included in the 'Bcc' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
smil of type DOMString,
Contains the SMIL component, i.e. the presentation element that determines the way the content of the MMS message MUST be displayed.
attachments of type array of MmsAttachment,
Contains the set of attachments of the MMS message.

14. MmsAttachment Dictionary

dictionary MmsAttachment {
             DOMString contentID;
             DOMString contentLocation;
             Blob      content;
};

14.1 Dictionary MmsAttachment Members

contentID of type DOMString,
The Content-ID parameter that MAY be used to refer to the attachment from the SMIL presentation object as described in [MMS13] and [MIME-ENC]. At least one of contentID and contentLocation MUST be specified if the MMS Message contains an SMIL presentation object.
contentLocation of type DOMString,
The Content-Location parameter that MAY be used to refer to the attachment from the SMIL presentation object as described in [MMS13] and [MIME-ENC]. At least one of contentID and contentLocation MUST be specified if the MMS Message contains an SMIL presentation object. It may also be used as a hint to define the filename when the attachment is stored at the file system.
content of type Blob,
The Blob object containing the media type and the content of the attachment.

15. MmsDeliveryInfo Dictionary

dictionary MmsDeliveryInfo {
             DOMString      recipient;
             DeliveryStatus deliveryStatus;
             Date           deliveryTimestamp;
             ReadStatus     readStatus;
             Date           readTimestamp;
};

15.1 Dictionary MmsDeliveryInfo Members

recipient of type DOMString,
The recipient of the MMS to which the delivery status is related.
deliveryStatus of type DeliveryStatus,
The delivery status of the MMS message to a specific recipient.
deliveryTimestamp of type Date,
The time the message was delivered to the recipient, i.e. the 'Date' field in the M-Delivery.ind Protocol Data Unit [MMS13]. It is not provided if there is no positive knowledge about the delivery of the message.
readStatus of type ReadStatus,
The read status of the MMS message to a specific recipient.
readTimestamp of type Date,
The time the message was read by the recipient, i.e. the 'Date' field in the M-Read-Orig.ind Protocol Data Unit [MMS13]. It is not provided if there is no positive knowledge about the delivery of the message.

16. Conversation Interface

The Conversation interface represents a set of messages that are grouped together either because they are exchanged among the same set of participants or because they have the same subject.

interface Conversation {
    readonly    attribute DOMString     conversationID;
    readonly    attribute MessageType   type;
    readonly    attribute DOMString[]   participants;
    readonly    attribute DOMString     subject;
    readonly    attribute DOMString[]   messageTypes;
    readonly    attribute unsigned long messageCount;
    readonly    attribute unsigned long unreadCount;
    readonly    attribute DOMString     lastMessageID;
    readonly    attribute MessageCursor cursor;
};

16.1 Attributes

conversationID of type DOMString, readonly
MUST return the identifier of the conversation, which is globally unique within the implementation, i.e. there cannot be any other conversation with the same identifier.
type of type MessageType, readonly
MUST return the type of conversation, with value 'participants' if the conversation is defined as the set of messages exchanged among the same set of parties, and 'subject' if the conversation is defined as the set of messages with the same subject.
participants of type array of DOMString, readonly
MUST return an array containing the participants in the conversation. In case the conversation is of type 'subject' and there are messages in the conversation with a different set of participants then this attribute MUST return the union of the participants of all the messages in the conversation.
subject of type DOMString, readonly
MUST return the subject of the conversation, if there is a single one.
messageTypes of type array of DOMString, readonly
MUST return an array contining the different types of messages included in the conversation.
messageCount of type unsigned long, readonly
MUST return the number of messages in the conversation.
unreadCount of type unsigned long, readonly
MUST return the number of unread messages in the conversation.
lastMessageID of type DOMString, readonly
MUST return the identifier of the message in the conversation with the most recent timestamp.
cursor of type MessageCursor, readonly
MUST return the MessageCursor to access the messages in this conversation.

17. MessagingCursor Interface

The MessagingCursor interface allows to iterate through a list of Conversation elements or of messages (SmsMessage and/or MmsMessage elements).

A MessagingCursor always has, an associated request which is the Promise that created it.

As soon as the MessagingCursor is accessing an element, it MUST put its associated request in the 'processing' readyState, and set the result to null. Then, the UA MUST fetch the next/previous element asynchronously. When the element is retrieved, the associated request's readyState must be set to 'done' and the result must point to the cursor. If no element was found, the cursor's element property must return null.

interface MessagingCursor {
    readonly    attribute any? element;
    void next ();
    void previous ();
};

17.1 Attributes

element of type any, readonly , nullable
This property MUST return the currently accessed element. If the cursor went past the last element or if it is currently accessing the next element, it MUST return null.

17.2 Methods

next
When this method is called, the cursor MUST change its internal state to accessing an element and proceed to access to the next element.
If this method is called while the cursor is in the process of accessing an element, the method MUST throw an "InvalidStateError" error as defined in [DOM4].
No parameters.
Return type: void
previous
When this method is called, the cursor MUST change its internal state to accessing an element and proceed to access to the previous element.
If this method is called while the cursor is in the process of accessing an element, the method MUST throw an "InvalidStateError" error as defined in [DOM4].
No parameters.
Return type: void

18. ReceivedMessage Interface

The ReceivedMessage interface represents a system message related to a received message. This event is originated from the system and will start the application if it is not currently running.

The application that consumes this API SHOULD set a message handler for the ReceivedMessage system message to listen for when a system message related to a received message is fired.

interface ReceivedMessage {
    readonly    attribute (SmsMessage or MmsMessage) message;
};

18.1 Attributes

message of type (SmsMessage or MmsMessage), readonly
MUST return the SmsMessage or MmsMessage object to which this system message is related.

19. DeliveryReport Interface

The DeliveryReport interface represents a system message related to a delivery report of a sent message. This event is originated from the system and will start the application if it is not currently running.

The application that consumes this API MAY set a message handler for the DeliveryReport system message to listen for when a system message related to a received delivery report is fired.

interface DeliveryReport {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     deliveryTimestamps;
};

19.1 Attributes

serviceID of type DOMString, readonly
MUST return the identifier of the service used to send the message to which this delivery report is related.
messageID of type DOMString, readonly
MUST return the identifier of the message to which this delivery report is related.
recipients of type array of DOMString, readonly
MUST return an array containing the addresses of the subset of the original recipients of the message to which this delivery report is related. As delivery reports related to just part of the recipients of the MMS message are possible, this array may not contain the full list of recipients to which the MMS message was sent. If the delivery report is related to an SMS message then the array will contain a single item corresponding to the single recipient of the SMS message.
deliveryTimestamps of type array of Date, readonly , nullable
MUST return an array containing the delivery dates for each of the recipients to which this delivery report event relates. Each element in the array refers to the recipient in the same position of the recipients array. It MUST return null if case of delivery failure (e.g. message expired)

20. ReadReport Interface

The ReadReport interface represents a system message related to a read report of a sent MMS message. This event is originated from the system and will start the application if it is not currently running.

The application that consumes this API MAY set a message handler for the ReadReport system message to listen for when a system message related to a received read report is fired.

interface ReadReport {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     readTimestamps;
};

20.1 Attributes

serviceID of type DOMString, readonly
MUST return the identifier of the service used to send the message to which this read report is related.
messageID of type DOMString, readonly
MUST return the identifier of the message to which this read report is related.
recipients of type array of DOMString, readonly
MUST return an array containing the addresses of the subset of the original recipients of the message to which this read report is related. As read reports related to just part of the recipients of the MMS message are possible, this array may not contain the full list of recipients to which the MMS message was sent.
readTimestamps of type array of Date, readonly , nullable
MUST return an array containing the read dates by each of the recipients to which this read report event relates. Each element in the array refers to the recipient in the same position of the recipients array.

21. MessagingEvent Interface

The MessagingEvent interface represents events related to a message sent or received.

interface MessagingEvent {
    readonly    attribute (SmsMessage or MmsMessage) message;
};

21.1 Attributes

message of type (SmsMessage or MmsMessage), readonly
MUST return the SmsMessage or MmsMessage object to which this event is related.

22. DeliveryReportEvent Interface

The DeliveryReportEvent interface represents events related to a delivery report of a sent message.

interface DeliveryReportEvent : Event {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     deliveryTimestamps;
};

22.1 Attributes

serviceID of type DOMString, readonly
MUST return the identifier of the service used to send the message to which this delivery report event is related.
messageID of type DOMString, readonly
MUST return the identifier of the message to which this delivery report event is related.
recipients of type array of DOMString, readonly
MUST return an array containing the addresses of the subset of the original recipients of the message to which this delivery report event is related. As delivery reports related to just part of the recipients of the MMS message are possible, this array may not contain the full list of recipients to which the MMS message was sent. If the delivery report is related to an SMS message then the array will contain a single item corresponding to the single recipient of the SMS message.
deliveryTimestamps of type array of Date, readonly , nullable
MUST return an array containing the delivery dates for each of the recipients to which this delivery report event relates. Each element in the array refers to the recipient in the same position of the recipients array. It MUST return null if case of delivery failure (e.g. message expired)

23. ReadReportEvent Interface

The ReadReportEvent interface represents events related to a read report of a sent message.

interface ReadReportEvent : Event {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     readTimestamps;
};

23.1 Attributes

serviceID of type DOMString, readonly
MUST return the identifier of the service used to send the message to which this read report event is related.
messageID of type DOMString, readonly
MUST return the identifier of the message to which this read report event is related.
recipients of type array of DOMString, readonly
MUST return an array containing the addresses of the subset of the original recipients of the message to which this read report event is related. As read reports related to just part of the recipients of the MMS message are possible, this array may not contain the full list of recipients to which the MMS message was sent.
readTimestamps of type array of Date, readonly , nullable
MUST return an array containing the read dates for each of the recipients to which this read report event relates. Each element in the array refers to the recipient in the same position of the recipients array.

24. ServiceChangeEvent Interface

The ServiceChangeEvent interface represents events related to messaging services enabled or disabled.

interface ServiceChangeEvent : Event {
    readonly    attribute DOMString serviceID;
};

24.1 Attributes

serviceID of type DOMString, readonly
MUST return the identifier of the messaging service which is enabled or disabled.

25. MessagingFilter Dictionary

The MessagingFilter Dictionary represents a filter that is used to select a set of messages (e.g. to be provided upon invoking the findMessages or the findConversations method in the Messaging interface).

dictionary MessagingFilter {
             MessageType            type;
             Date                   startDate;
             Date                   endDate;
             DOMString              from;
             sequence<DOMString>    recipients;
             (SmsState or MmsState) state;
             DOMString              serviceID;
             boolean                read;
};

25.1 Dictionary MessagingFilter Members

type of type MessageType,
Indicates whether just the SMS or MMS messages are to be provided in the results of this filter, respectively if it is set to string value 'SMS' or 'MMS'.
startDate of type Date,
Indicates that messages with timestamp previous to this date will not be provided in the results of this filter.
endDate of type Date,
Indicates that messages with timestamp after this date will not be provided in the results of this filter.
from of type DOMString,
Indicates that just messages sent from this number are to be provided in the results of this filter.
recipients of type sequence<DOMString>,
Indicates that just messages sent to one of these numbers are to be provided in the results of this filter.
state of type (SmsState or MmsState),
Indicates whether the results of this filter just needs to return the messages matching the indicated state.
serviceID of type DOMString,
Indicates that just messages associated to the messaging service with this identifier are to be provided in the results of this filter.
read of type boolean,
Indicates whether just read or unread messages are to be provided in the results of this filter, respectively if it is set to 'true' or 'false'.

26. FilterOptions Dictionary

dictionary FilterOptions {
             DOMString     sortBy;
             DOMString     sortOrder;
             unsigned long limit;
};

26.1 Dictionary FilterOptions Members

sortBy of type DOMString,
Indicates the attribute on which the filtered messages are sorted.
sortOrder of type DOMString,
Indicates the order on which the filtered messages are sorted with possible values 'ascending' and 'descending'.
limit of type unsigned long,
Indicates the maximum number of messages that can be returned as a result of applying the corresponding filter.

27. Enumerations

The attibute type can have the following values:

enum MessageType {
    "sms",
    "mms"
};
Enumeration description
sms Corresponding to SMS message(s).
mms Corresponding to MMS message(s).

The attibute messageClass in an SmsMessage can have the following values:

enum MessageClass {
    "class-0",
    "class-1",
    "class-2",
    "class-3",
    "normal"
};
Enumeration description
class-0 The message is of class 0.
class-1 The message is of class 1.
class-2 The message is of class 2.
class-3 The message is of class 3.
normal The message is of class 1 (same as 'class-1').

The attibute state in an SmsMessage can have the following values:

enum SmsState {
    "received",
    "sending",
    "sent",
    "failed"
};
Enumeration description
received The message is an inbound message.
sending The message is in process of being sent.
sent The message has been successfully sent.
failed The message is an outbound message whose submission has failed.

The attibute state in an MmsMessage can have the following values:

enum MmsState {
    "not-downloaded",
    "fetching",
    "received",
    "sending",
    "sent",
    "failed"
};
Enumeration description
not-downloaded The message is an inbound message, for which an MMS notification has been received but that has not yet been downloaded.
fetching The message is an inbound message, for which an MMS notification has been received, and whose download has started and not yet finished.
received The message is an inbound message.
sending The message is in process of being sent.
sent The message has been successfully sent.
failed The message is an outbound message whose submission has failed.

The attibute deliveryStatus can have the following values:

enum DeliveryStatus {
    "success",
    "pending",
    "error",
    "not-applicable"
};
Enumeration description
success The message has been succesfully delivered to the recipient.
pending The message is pending delivery.
error The delivery of the message has failed.
not-applicable The delivery status is not applicable either because a delivery report has not been requested or because the message is an inbound message

The attibute readStatus can have the following values:

enum ReadStatus {
    "success",
    "pending",
    "error",
    "not-applicable"
};
Enumeration description
success The message has been read by the recipient.
pending There is no positive knowledge that the message has been read by the recipient.
error The delivery of the message has failed.
not-applicable The read status is not applicable either because a read report has not been requested or because the message is an inbound message

The MMS fetch mode can have the following values:

enum FetchMode {
    "automatic",
    "automatic-home",
    "manual",
    "never"
};
Enumeration description
automatic MMS message is fecthed right after the reception of the MMS notification.
automatic-home MMS message is fecthed right after the reception of the MMS notification if the device is located in the home network, i.e. not roaming, otherwise the message will be fetched upon the device entering in the home network again or the user manually requesting it.
manual The message is not fecthed until the user manually requests it.
never MMS message retrieval is completely disabled.

28. Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team and specially to Jonas Sicking, Mounir Lamouri and Vicamo Yang for their technical guidance, implementation work and support.

A. References

A.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 28 April 2015. W3C Last Call Working Draft. URL: http://www.w3.org/TR/dom/
[GSM-SMS]
Richard Burbidge. Technical realization of the Short Message Service (SMS). URL: http://www.3gpp.org/ftp/Specs/html-info/23040.htm
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[MIME-ENC]
J. Palme; A. Hopmann; N. Shelness. MIME Encapsulation of Aggregate Documents, such as HTML (MHTML). March 1999. Proposed Standard. URL: https://tools.ietf.org/html/rfc2557
[MMS13]
Multimedia Messaging Service 1.3. 13 September 2011. Approved Enabler Release. URL: http://technical.openmobilealliance.org/Technical/release_program/mms_v1_3.aspx
[RFC2046]
N. Freed; N. Borenstein. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/

A.2 Informative references

[OMA-PUSH]
Open Mobile Alliance. OMA Push Version 2.3. URL: http://www.openmobilealliance.org/Technical/release_program/push_v2_3.aspx