WebTelephony API and WebSMS API – Part of WebAPI

As discussed and shown in Mozilla’s Boot to Gecko – The Web is the Platform and Gaia, Mozilla’s user interface for Boot to Gecko, the web is becoming a very powerful platform! Therefore I want to introduce you to two exciting APIs, from our WebAPI initiative: WebTelephony and WebSMS.


The basis of accessing the phone functionality is simply through navigator.mozTelephony. Once you have a reference to that object you can start placing and recieving calls. Here are a few examples:

// Telephony object
var tel = navigator.mozTelephony;

// Check if the phone is muted (read/write property)

// Check if the speaker is enabled (read/write property)

// Place a call
var call = tel.dial("123456789");

// Events for that call
call.onstatechange = function (event) {
        Possible values for state:
        "dialing", "ringing", "busy", "connecting", "connected",
        "disconnecting", "disconnected", "incoming"

// Above options as direct events
call.onconnected = function () {
    // Call was connected

call.ondisconnected = function () {
    // Call was disconnected

// Receiving a call
tel.onincoming = function (event) {
    var incomingCall = event.call;

    // Get the number of the incoming call

    // Answer the call

// Disconnect a call

// Iterating over calls, and taking action depending on their changed status
tel.oncallschanged = function (event) {
    tel.calls.forEach(function (call) {
        // Log the state of each call

Telephony is currently available from the dialer and homescreen in Gaia.


Another part of core functionality in a mobile phone is sending and receiving SMS messages. Here is how to do that:

// SMS object
var sms = navigator.mozSMS;

// Send a message
sms.send("123456789", "Hello world!");

// Recieve a message
sms.onrecieved = function (event) {
    // Read message

Hack and contribute

If you are interested in delving more into this and its inner workings, I recommend checking out Mozilla’s user interface for Boot to Gecko, Gaia. In there, you can take a look at the dialer.js file and the sms.js file.

And if you think using your web technology skills for developing and customizing mobile phones as well, don’t hesitate to check out and contribute to Gaia!

About Robert Nyman [Editor emeritus]

Technical Evangelist & Editor of Mozilla Hacks. Gives talks & blogs about HTML5, JavaScript & the Open Web. Robert is a strong believer in HTML5 and the Open Web and has been working since 1999 with Front End development for the web - in Sweden and in New York City. He regularly also blogs at http://robertnyman.com and loves to travel and meet people.

More articles by Robert Nyman [Editor emeritus]…


  1. Juarez

    1. Why not a future proof desing?

    var tel = navigator.getDevice(“phone”);

    2. How can I handle a dual SIM phone like the LG Optimus Net Dual or the Samsung Y Pro Duos ?

    March 1st, 2012 at 13:15

    1. Robert Nyman

      1. Since it’s an experimental API, and before it’s standardized, it’s implemented with a vendor prefix (since current implementation and future standardized one might not look the same).
      2. Great question! I assume it would trigger the native behavior on the phone to make you choose from one of the available SIM cards.

      March 1st, 2012 at 13:29

      1. SignpostMarv

        Why not navigator.mozTelephony[0], navigator.mozSMS[0] etc ?

        March 1st, 2012 at 15:02

        1. Robert Nyman

          With Dual SIM cards? Sure, but I’m guessing that most phones will only have one, and, in my opinion, rather make it easy for coding on the majority of devices, and then let the ones with dual SIM cards handle the exception.

          March 1st, 2012 at 15:19

          1. SignpostMarv

            Have the mozTelephony/mozSMS be arrays that also implement the methods of their child types?

            March 1st, 2012 at 15:39

          2. Robert Nyman

            What I meant was that if the majority won’t have dual SIMs, using an array would just be tedious for developers. Therefore, I believe having just an object (that in the future might have a property for accessing dual SIMs) seems like a better approach.

            March 1st, 2012 at 15:44

  2. tack

    To expand on Juarez’s example (var tel = navigator.getDevice(“phone”);) it would be very powerful for the default or fallback device to be the telephony bits in the handset but given a parameter a different connection could be used. Specifically I’m thinking of VoIP and Skype. For instance if you have an Asterisk PBX in your organization it would be good to try to connect to that first using SIP on the company wifi and fall back onto the carrier provided connection if it fails. Also, it would be nice if groupware apps could offer telephony in desktop browsers through this API. So say you’re a small business… half of your employees only use their desk phone once a month… use this for them and shell out the big bucks for fancy phones for heavy phone users.

    March 1st, 2012 at 16:16

    1. Robert Nyman

      I agree, it’s definitely interesting! Not sure that specific syntax would help with that, but it is for sure something to take into consideration.

      March 1st, 2012 at 16:25

  3. David Higgins

    I was wondering how the Gaia demo was going to interface with telephony itself. When I saw Paul’s demo, I was scratching my head wondering how this ‘web technology’ could talk to the phone carriers. Now after seeing this post, it’s all abundantly clear.

    BTG brings up new questions for Mozilla devevlopers, because now one can do anything with it. It doesn’t have to be just phones.

    With the advent of tablets, there is room for entire Operating systems to be built on this. We even have an arsenal of “bad Windows 98 screensavers” as Chris calls them with the canvas API, so no shortage of GFX to add to the screensaver section of the OS, :)

    I also love the way BTG is entirely un-affiliated with Android. I never liked Java, and I dislike the way Android gets updated too often, thus needing to buy a whole new device every 8-10 months or so when a new dazzling update from Android comes out.

    Hopefuly BTG will have a better more accomadating release cycle.

    Sure, I can install the new Android manually, but meh, I’m lazy, and proud of it.


    March 1st, 2012 at 16:28

    1. Robert Nyman

      Glad you like it!
      And yes, definitely, the implications of the things that will be possible to implement and customize are huge!

      March 1st, 2012 at 16:34

  4. pd

    It’s good to see that Mozilla seems to be adopting simpler jQuery style sytax rather than that horrible old [@mozill.org;getServices] or so on and so forth.

    March 2nd, 2012 at 05:43

    1. Robert Nyman

      Not sure I’d call it jQuery-style myself – many DOM methods have looked similar for a long time – but I definitely agree that we should always aim for a short and readable syntax.

      March 2nd, 2012 at 05:48

Comments are closed for this article.