Using the Web Telephony API

This article explains the basics of getting started with the Web Telephony API.

Setting Manifest permissions

To use this API in a Firefox OS app, the manifest.webapp file needs to contain the following:

"type": "certified",
"permissions": {
  "telephony": {
    "description": "Required to control telephony functions"
  }
},

Accessing the API

The starting point for accessing device phone functionality is Navigator.mozTelephony. Once you have a reference to that object you can start placing and receiving calls.

// Telephony object
var tel = navigator.mozTelephony;

Inspecting the device hardware

The resulting Telephony object represents the phone hardware programmatically, and gives you the ability to control many aspects of it. For example, you can mute/unmute, and enable/disable the speaker phone:

// Check if the phone is muted (read/write property)
console.log(tel.muted);

// Check if the speaker is enabled (read/write property)
console.log(tel.speakerEnabled);

Making calls

Making a call is as simple as calling Telephony.dial on your Telephony object — this is a promise-based API as of Firefox OS 1.4 (it was a standard callback before that) which resolves with a TelephonyCall object that represents the call. This object contains a number of properties, methods and handlers to allow you to monitor the call's properties, perform actions such as hanging up and holding the call, and reacting to changes in call state.

// Place a call
var call = tel.dial("123456789").then(function(call) {

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

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

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

Receiving calls

Receiving calls is different but still simple. You have to write a Telephony.onincoming event listener that will fire when a call is incoming; the function contains an event object — CallEvent — that contains a call property allowing you to get access to the call's TelephonyCall object and perform actions like answering the call, etc.

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

  // Get the number of the incoming call
  console.log(incomingCall.id);

  // Answer the call
  incomingCall.answer();
  
  // Let's say we have a button set up to hang up the call when pressed.
  hangupButton.onclick = function() {
    // Disconnect a call
    call.hangUp();
  }
};

Multiple calls can be active on a device at the same time. You can iterate over each via the Telephony.calls property and take action on each one as appropriate.

// 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
    console.log(call.state); 
  });
};

Specifications

Browser compatibility

For obvious reasons, support is primarily expected on mobile browsers.

See also

• WebTelephony