The Device APIs Working Group is currently not pursuing the approach outlined in this draft, so it should be considered historical. Please treat this document with caution and do not reference it or use it as the basis for implementation. The domain covered by this document is still within the scope of the Working Group as defined in its Charter. The Working Group may pursue an alternative API design that is based on the current Web browser security model.

The Contacts API provides a method to send messages based on URIs (e.g. email, MMS, SMS) with optional attachments.

This draft proposes a vastly different approach to the previously published version, using URI schemes as a way to address different messaging protocols instead of using separate methods. The group is specifically looking for feedback on which approach is felt like the most useful.

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

Since not all devices have all messaging functionality (e.g. a phone may have only SMS and MMS while a PC may have only e-mail), conformant implementations need only expose available functionality.

Implementations that use ECMAScript to expose the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].

Introduction

The Messaging API provides a method to send messages based on URIs (e.g. email, MMS, SMS) with optional attachments.

This API complements what sms:, mms:, and mailto: URI schemes provide with:

The following code shows how to send a message with an attachment:

<p><label>Load file to attach: <input type="file" id='attachment'></p>
<p><input type='submit' value='Send' id='send'></p>
lt;script>
function successCB() {
   alert("The Message has been sent successfully");
}

function errorCB(error) {
   alert("The Message could not be sent " + error.code);
}

document.getElementById('send').addEventListener('click', send, false);

function send() {
  if (navigator.sendMessage) {
     picture = document.getElementById('attachment').files[0];
     navigator.sendMessage("mms:+460000000001?body=Welcome%20%to%Atlantis", [picture], successCB, errorCB);
 }
}    
</script>

Security Considerations

The API defined in this specification can be used to create and send messages through different technologies. Sending messages usually has an associated cost (especially SMSs and MMSs), hence a conforming implementation of this specification should provide a mechanism that ensures that no message is sent without the user's consent.

Since the implications of sending a given message may depend on the message attributes (e.g. destination address) and content, the approach used to ensure user’s consent should include the relevant information, typically the type of message and its destination address.

A typical (but not required) way of ensuring user’s consent would be to use the same mechanism as the one used when the user click on a link using one the relevant URI schemes, for instance, bringing up the platform messaging application with pre-filled fields and pre-defined attachments.

In general, user’s consent is expected to be confirmed for each invocation of the sendMessage methods. Typically, the user agent would bring forward the application responsible for editing/sending the type of message with pre-filled entries, allowing the user to send the message through the said application (after edits if she wants so.)

Supported messaging types

The specification supports sending messages on top of protocols for which a URI scheme has been defined, including SMS, MMS and emails.

Using a single method to send message across many protocols make it impossible to detect whether a given user agent supports a specific messaging protocol.

API Description

NavigatorMessaging

The NavigatorMessaging object is exposed on the navigator object

navigator.sendMessage is a strawman proposal at this time. Further investigation on possible clash with existing code is still needed.

void sendMessage()
Sends a message with attachments to the specified address.
DOMString uri
a URI that specificies the address to which the message is to be sent; that URI may contain query string parameters that specify additional headers and the body of the said message
optional sequence<Blob>? attachments
A list of Blob objects that represent attachments to be sent with the message; only applicable to protocols that support the notion of attachments. Using this parameter on protocols that don't support attachments triggers an error.
optional messagingSuccessCB successCB
A callback function called when the messaging application reports success on sending the message.
optional messagingErrorCB errorCB
A callback function called when there was an error with sending the message.

MessagingSuccessCB

void onSuccess ()
This interface defines the method invoked asynchronously when the messaging application reports success on sending the message.

MessagingErrorCB

void onError (in MessagingError error )
This interface defines the method invoked when the messaging application could not be invoked or reported failure on sending the message.
MessagingError error
Error response provided by the device.

MessagingError

The MessagingError interface encapsulates all errors in the manipulation of Messaging objects in the messaging API.

const unsigned short UNKNOWN_ERROR = 0
An unknown error occurred.
const unsigned short SENDING_FAILED = 1
The messaging application failed to send the message.
const unsigned short MUA_NOTFOUND = 2
The user agent was unable to connect with the messaging application.
const unsigned short NOT_SUPPORTED = 3
The user agent cannot send message to the given URI scheme.

Acknowledgements

...