Introduction to Mobile Message API

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

This API is available on Firefox OS for internal applications only.

Summary

A part of the core functionality in a mobile phone is sending and receiving SMS and MMS messages. This is achieved through the Messaging API. As this new specification is in its early stage, Firefox OS implements a non-standard version of this. Here is a little overview of that API as implemented.

The main entry point for that API is the navigator.mozMobileMessage object which is an instance of MozMobileMessageManager. It allows to perform all the managing actions required to manipulate SMS and MMS messages.

Sending messages

SMS

An SMS is basically a text made of 160 characters. So to send an SMS it just requires to call the MozMobileMessageManager.send() method with the appropriate text and the phone number of the recipient for the message.

var message = "Hi!";
var number = "1234"; // There are several ways to retrieve a valid phone number

navigator.mozMobileMessage.send(number, message);

However, there are some tricky rules regarding the size of an SMS, so before sending any message, it's considered best practice to check for the right size of your message. If your message is too long, you have to split it into segments and send a different SMS for each segment. To deal with that sizing issue, you just have to use the MozMobileMessageManager.getSegmentInfoForText() which returns a MozSmsSegmentInfo object.

// Assuming `message` and `number` variables

var info = navigator.mobileMessage.getSegmentInfoForText(message);
var msg  = "";
var pos  = 0;
var size = 0;

for (var i = 0; i < info.segments; i++) {
  pos  = i * info.charsPerSegment;
  size = i < info.segments - 1 
       ? info.charsPerSegment 
       : info.charsAvailableInLastSegment;

  msg = message.substr(pos, size);

  navigator.mozMobileMessage.send(number, msg);
}

Once the send method is called, it returns a DOMRequest to handle the success or error of the sending operation. It's possible to send an SMS to more than one recipient at a time. To do so, it just requires to pass an Array of strings instead of a single string to the send method. In that case, the method returns an Array of DOMRequest, each of them allowing to handle the success or error of the sending process for each recipient.

In all cases, if the request is successful, the request's result is a MozSmsMessage object.

// Assuming `message`is a string and `numbers` an Array of strings

var request, msg, pos, size, i,
    info = navigator.mobileMessage.getSegmentInfoForText(message);

for (i = 0; i < info.segments; i++) {
  pos  = i * info.charsPerSegment;
  size = i < info.segments - 1 
       ? info.charsPerSegment 
       : info.charsAvailableInLastSegment;

  msg = message.substr(pos, size);

  requests = navigator.mozMobileMessage.send(numbers, msg);

  requests.forEach(function (request) {
    request.onsuccess = function () {
      console.log('The SMS has been sent to ' + this.result.receiver)
    }

    request.onerror = function () {
      console.log('Something goes wrong: ' + this.error)
    }
  });
}

MMS

MMS messages are a bit harder to manage because their content is not plain text but a full SMIL document. Once you have managed to build such a document, it can be sent with the MozMobileMessageManager.sendMMS() method. It expects a parameter object that will provide all the necessary information about the MMS. This object expects the following properties:

receivers : An Array of strings; each string is the phone number of a receiver for the message.
subject : A string representing the subject of the message.
smil : The stringified SMIL document representing the MMS's content.
attachments : The necessary assets required by the MMS (for example: images, videos, text, etc.) Each asset is a Blob object.

// Assuming `file` is a Blob representing an image
// Assuming `numbers` is an Array of strings representing phone numbers

var message = {
  receivers: numbers,
  subject: "Pic from my wedding"
  smil: '<smil><body><par>' +
        '<img src="wedding.jpg" />' +
        '<text src="txt" />' +
        '</par></body></smil>',
  attachments: [
    {
      location: 'txt',
      content : new Blob(['Me and my wife'], {type: 'text/plain'})
    },
    {
      location: 'wedding.jpg',
      content : file
    }
  ]
}

navigator.mozMobileMessage.sendMMS(message);

Whether you send an MMS to one or many recipients, the sendMMS method always returns one single DOMRequest object to handle the success or error of the sending operation. In case of success, the request's result is a MozMmsMessage which provides information about the success of the sending to each recipient through its deliveryStatus property.

Sending workflow

Each time a message is sent, it enters an ending workflow. This workflow will send events in order to track it and to react to any change in this workflow.

sending : the message has entered the sending workflow.
sent : the message has been sent to the recipients
or failed if something goes wrong.
deliverysuccess : the message has been received by a recipient
or deliveryerror if the recipient was unable to get the message.

It's possible to listen for those events at the MozMobileMessageManager level with the basic on* properties or through the addEventListener method. The callback functions used as event handler will get a MozSmsEvent or MozMmsEvent as input parameter.

navigator.mozMobileMessage.addEventListener('sending', function (e) {
  console.log("Queueing a message to be sent to: " + (e.message.receiver || e.message.receivers));
});

navigator.mozMobileMessage.addEventListener('sent', function (e) {
  console.log("Message sent to: " + (e.message.receiver || e.message.receivers));
});

navigator.mozMobileMessage.addEventListener('failed', function (e) {
  console.log("Unable to send a message to: " + (e.message.receiver || e.message.receivers));
});

navigator.mozMobileMessage.addEventListener('deliverysuccess', function (e) {
  console.log("Message received by: " + (e.message.receiver || e.message.receivers));
});

navigator.mozMobileMessage.addEventListener('deliveryerror', function (e) {
  console.log("Message NOT received by: " + (e.message.receiver || e.message.receivers));
});

Receiving messages

Each time the device receives a message, it will enter a retrieving workflow. This workflow will send events in order to track it and to react to any change in this workflow.

retrieving : A message has entered the retrieving workflow (this event only occurs for MMS as they have to be downloaded and it can take a significant amount of time, depending on the assets of the message).
received : A message has been received.

At that point, you are able to do whatever you want with those messages (note that SMS, for example, has handling rules defined through their messageClass property). However, they are automatically stored on the device and can be retrieved (see below).

Handling messages

Accessing messages

There are several ways of accessing the messages stored on the device.

To get a single known message, it's possible to use the MozMobileMessageManager.getMessage() for SMS or MozMobileMessageManager.retrieveMMS() for MMS.

To access a list of messages, it can be done with the MozMobileMessageManager.getMessages() method. This method expects a MozSmsFilter as its first parameter (despite its name, this object is also used to filter MMS messages). Such an object is used to define filtering parameters. It allows to filter messages by date, read status, recipients, delivery status, or thread (messages are stored by discussion thread in order to make such recovering easier. All threads can be accessed with the MozMobileMessageManager.getThreads() method.)

// In this example we want to access all the messages of the thread related to an incoming message

navigator.mozMobileMessage.addEventListener('received', function (msg) {
  var threadId = msg.threadId;

  var filter = new MozSmsFilter();
  filter.threadId = threadId;

  // Get the messages from the latest to the first
  var cursor = navigator.mozMobileMessage.getMessages(filter, true);

  cursor.onsuccess = function () {
    var message = this.result;
    var time = message.timestamp.toDateString()

    console.log(time + ': ' + (message.body || message.subject)); // SMS || MMS

    if (!this.done) {
      this.continue();
    }
  }
});

Other actions

deleting messages via MozMobileMessageManager.delete().
changing the read/unread state of a message via MozMobileMessageManager.markMessageRead().