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
Specification | Status | Comment |
---|---|---|
Web Telephony | Draft | Draft |
Browser compatibility
For obvious reasons, support is primarily expected on mobile browsers.
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | No support | No support | No support | No support | No support |
Feature | Android | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | No support | 12.0 (12.0) | 1.0.1 | No support | No support | No support |
id and secondId |
No support | 30.0 (30.0) | 2.0 | No support | No support | No support |
disconnectedReason |
No support | 37.0 (37.0) | 2.2 | No support | No support | No support |