The Messaging API

Introduction

This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and email. It includes APIs to create and send messages. These APIs complement what sms:, mms:, and mailto: URI schemes provide with:

• the possibility to attach files to messages,
• A callback on success / error when a message is sent.

Use case

To describe use case, first I would say many browser today already support messaging by supporting frequently used ‘mailto’, and not so frequently used ‘sms’ URIs. While the API certainly addresses a different use case (access from scripting code), it would be very useful to describe how the URI-initiated messaging is different or equivalent to the API-initiated messaging. For example, should browsers make sure that the user experience is always consistent across these two methods of messaging? Or is it acceptable if URI-based messaging uses an external user agent whereas API-based messaging uses a browser's internal capabilities?

At the very least, it would be useful to point out that URI-based messaging exists, and that page authors have the option of using URIs instead of having to write scripting code. in terms of accessibility and platform robustness, it will be quite a while until page authors could rely on the API alone; at least as a fallback solution, messaging URIs probably always are a good idea.

Since not all devices will have all messaging functionality (e.g. a phone may have only SMS and MMS while a PC may have only e-mail) there is a need to indicate that implementations need only expose available functionality.

Examples

The following code extracts illustrate how to create and send messages. Sending an MMS with an attached picture, if device supports it.

function successCB() {

   alert("The Message has been sent successfully");

}

function errorCB(error) {

   alert("The Message could not be sent " + error.code);

}

if (navigator.device.sendMessage) {

   picture = document.getElementById('attachment').files[0];

   navigator.device.sendMessage("mms:+460000000001?body=Welcome%20%to%Atlantis", [picture], successCB, errorCB);