This specification defines a System Level API which offers a simple interface to manage telephony calls. A typical use case of the Web Telephony API is the implementation of a 'Dialer' application.

Introduction

The Telephony API allows applications to manage the full lifecycle of telephone calls.

An example of use is provided below: 

            var telCall = navigator.telephony.dial('+34638883076');
            telCall.onstatechange = function(e) {
              if (e.target.state == 'connected')
                window.console.log('Connected!');
            }

            telCall.onerror = function(e) {
              window.console.error(e);
            }

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

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

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fire a simple event are defined in [[!HTML5]].

The terms event handler and event handler event types are defined in [[!HTML5]].

An active call is a Telephony Call in the connected state and bound to the input and output devices (microphone, speaker and tone generator).

Security and privacy considerations

This API must be only exposed to trusted content

NavigatorTelephony Interface

The NavigatorTelephony interface is exposed on the Navigator object.

readonly attribute Telephony telephony
The object that exposes the telephony functionality.

Telephony Interface

The Telephony interface represents the initial entry point for getting access to telephony services.

attribute boolean speakerEnabled
Indicates whether the system's speaker is enabled or disabled.
attribute boolean headsetEnabled
Indicates whether the headset attached to the system is enabled or disabled.
attribute double audioVolume
Indicates the volume of the active audio output (speaker or headset) ranging from 0.0 (silent) to 1.0 (loudest).
attribute boolean audioMuted
Indicates whether the active audio output (speaker or headset) is muted or unmuted.
attribute double micVolume
Indicates the volume of the microphone input level ranging from 0.0 (silent) to 1.0 (loudest).
attribute boolean micMuted
Indicates whether the system's microphone is muted or unmuted.
readonly attribute DOMString[] ownTelNumbers
Indicates the telephone number, or list thereof, associated to this subscription to the Telephony service.
readonly attribute DOMString[] emergencyNumbers
Indicates the telephone number, or list thereof, of the emergency service in current geographical area.
readonly attribute TelephonyCall active
Represents the TelephonyCall that is active.
readonly attribute TelephonyCall[] calls
Returns an array with the list of instantiated calls. The attribute MUST be initialized to an empty array.
TelephonyCall dial ()
Allows to initiate a new TelephonyCall using this telephony service.
DOMString number
Indicates the destination number of the call
DialParams params
Indicates the parameters of the call (i.e. own number to be hidden or displayed)
void startTone()
This method starts emitting a DTMF tone in the active TelephonyCall object.
DOMString tone
Indicates the DTMF tone to be emitted with values (0-9; A-D; *; #)
void stopTone()
This method allows to stop the DTMF tone being emitted in the active TelephonyCall object.
void sendTone()
This method emits a DTMF tone with default duration in the active TelephonyCall object.
DOMString tone
Indicates the DTMF tone to be emitted with values (0-9; A-D; *; #)
attribute EventHandler onincoming
attribute EventHandler oncallschanged

The IDL attribute speakerEnabled MUST return true/false when the speakers are respectively enabled/disabled.

The IDL attribute headsetEnabled MUST return true/false when the headset is respectively enabled/disabled.

The IDL attribute audioVolume MUST return the normalized volume of the active audio output (speaker or headset) ranging from 0.0 (silent) to 1.0 (loudest).

The IDL attribute audioMuted MUST return true/false when the active audio output (speaker or headset) is respectively muted/unmuted.

The IDL attribute micVolume MUST return the normalized value of the microphone input level ranging from 0.0 (silent) to 1.0 (loudest).

The IDL attribute micMuted MUST return true/false when the microphone is respectively muted/unmuted.

The IDL attribute ownTelNumbers MUST return the telephone number (MSISDN) associated to this subscription to the Telephony service, or a list thereof (e.g. in case of Dual SIM with two associated numbers).

The IDL attribute emergencyNumbers MUST return the number of the emergency service in current geographical area, or a list thereof.

The IDL attribute active MUST return a TelephonyCall object if there is an active call. Otherwise it MUST return null.

The IDL attribute calls MUST return an array of all TelephonyCall objects present in the system. Otherwise it must return an empty list.

Whenever there is a change in the calls array the user agent MUST queue a task to fire a simple event named callschanged at Telephony object.

Whenever there is a change in the active TelephonyCall, the user agent MUST set the active attribute to the new active call.

The dial method when invoked MUST run the following steps:

  1. Let telCall be a newly created TelephonyCall object
  2. Set number of telCall to the telephone number specified in the number parameter
  3. If calls already contains a TelephonyCall object associated to the number parameter, then go to error steps.
  4. Otherwise, execute the following steps:
    1. Make a request to the telephony system to dial in the telephone number passed in the number parameter. According to the value of the displayNumber in the params parameter, own number is requested to be either displayed, hidden or otherwise the default system configuration to this regard is requested to be followed. If the request progress successfully, then
      1. Add telCall to the calls array
      2. Set the state of telCall to dialing.
      3. Queue a task to fire a simple event named statechange at the telCall object.
      4. Queue a task to fire a simple event named dialing at the telCall object.
      5. and finally return to the caller and queue a task TCallControl to monitor call flow progress.
    2. If during further steps for call connection there is an error go to error steps

TCallControl MUST listen to any event (originated by API client operations or by the telephony system itself) that results in a disconnection not caused by the remote party, and in that case the following steps MUST be run:

  1. Set the state of telCall to disconnected.
  2. Queue a task to fire a simple event named statechange at the telCall object.
  3. Queue a task to fire a simple event named disconnected at the telCall object.
  4. Remove the telCall object from the calls array at Telephony.

Upon a new incoming call, the user agent MUST:

  1. Let incomingCall be a new instance of TelephonyCall.
  2. Set the state of incomingCall to incoming in case there is no other call in connected state or otherwise to waiting
  3. Add incomingCall to the calls array
  4. Queue a task to fire a simple event named statechange at the incomingCall object.
  5. Queue a task to fire a simple event named incoming at the incomingCall object and
  6. Queue a task TCallControl to monitor call flow progress.

The incoming event has to be defined according to DOM4.

The startTone method when invoked MUST make a request to the telephony system to start sending the tone passed in the tone parameter to the active TelephonyCall object. If the request is acknowledged then return to the caller. If there is an error queue a task to fire a simple event named error at the Telephony object.

The stopTone method when invoked MUST make a request to the telephony system to stop sending tones to the active TelephonyCall object. If the request is acknowledged then return to the caller. If there is an error queue a task to fire a simple event named error at the Telephony object.

The sendTone method when invoked MUST make a request to the telephony system to send the tone passed in the tone parameter to the active TelephonyCall object with a default duration. If the request is acknowledged then return to the caller. If there is an error queue a task to fire a simple event named error at the Telephony object.

Error Steps

  1. Set the state of telCall to error.
  2. queue a task to fire a simple event named error at the telCall object.

Event handlers

The following are the event handlers (and their corresponding event handler types) that MUST be supported as attributes by the Telephony object:

event handler event handler event type
onincoming incoming
oncallschanged callschanged

DialParams Dictionary

optional DOMString displayNumber
Indicates whether the own number is to be hidden or displayed to the called remote party, or otherwise the default system configuration to this regard is to be followed. It may have the following values: 'display', 'hide' and 'default'.

TelephonyCall Interface

readonly attribute DOMString number
It MUST return the telephone number of the remote party.
readonly attribute DOMString state
It MUST return the state of the call (see below).
readonly attribute DOMError error
An error that occured during the call lifecycle. Errors are as defined in [[!DOM4]].
readonly attribute DOMString? reason
It MUST return the additional information available relative to the state of the call. At least the following values MUST be supported for the disconnected call state: "unknown", "local" (caller hung up), "remote" (remote party hung up, or is busy), "network" (network unreachable or busy, or error happened).
void answer()
This method answers an incoming telephone call.
void disconnect()
This method terminates a telephone call.
void hold()
This method puts a telephone call on hold.
void resume()
This method resumes a telephone call that had been previously put on hold.
void redirect(in DOMString redirectNumber)
This method redirects an incoming telephone call to another telephone number.
attribute EventHandler onstatechange
attribute EventHandler ondialing
attribute EventHandler onalerting
attribute EventHandler onaccepted
attribute EventHandler onconnecting
attribute EventHandler onconnected
attribute EventHandler ondisconnecting
attribute EventHandler ondisconnected
attribute EventHandler onholding
attribute EventHandler onheld
attribute EventHandler onresuming
attribute EventHandler onredirecting
attribute EventHandler onerror

The IDL attribute state MUST return the current status of the call. It MUST be one of the following values:

dialing (string value 'dialing')
A request to establish the call has been made and it is progressing
connecting (string value 'connecting')
An outbound call that has been dialed and is being connected, and thus is not yet alerting the callee
alerting (string value 'alerting')
The destination number has been reached and alerting is taking place
connected (string value 'connected')
The call is ongoing
disconnecting (string value 'disconnecting')
A request to disconnect the call has been made and it is progressing
disconnected (string value 'disconnected')
The call has been disconnected
incoming (string value 'incoming')
An incoming call that has been received whilst no other call was progressing and that has not been answered yet
waiting (string value 'waiting')
An incoming call that has been received whilst there was another call progressing
accepted (string value 'accepted')
An incoming call has been answered and is being connected
holding (string value 'holding')
The call is being put on hold
held (string value 'held')
The call has been put on hold
resuming (string value 'resuming')
The call, which was on hold, is being resumed
redirecting (string value 'redirecting')
The call is being redirected to another telephone number

The following figure depicts the state diagram for inbound calls, i.e. calls that are received

Inbound Call State Diagram

The following figure depicts the state diagram for outbound calls, i.e. calls that are dialed out

Outbound Call State Diagram

It needs to be discussed whether the above figures as well as the textual description of the state transitions are normative or not.

Whenever there is a change in the state attribute the user agent MUST:

  1. Queue a task to fire a simple event which name will be equal to the new value of the state attribute.
  2. Queue a task to fire a simple event named statechange

When TCallControl is notified that a dialed call is in the process of being connected, it MUST set state to connecting

When TCallControl is notified that call alerting tones are being sent it MUST set state to alerting.

When TCallControl is informed that the connection has been established, it MUST set state to connected.

If there is any error during call progressing then the error steps MUST be executed.

The disconnect method when invoked MUST issue a request to the telephony system to disconnect the call. If the request is acknowledged, then set state to disconnecting.

When TCallControl is notified of actual call disconnection it MUST set state to disconnected.

The hold method when invoked MUST run the following steps:

  1. If state is not equal to connected raise an ILLEGAL_STATE exception
  2. Otherwise make a request to the telephony system to hold the call. If the request is acknowledged then set state to holding.

When TCallControl is notified that the call has been put on hold it MUST set state to held.

The resume method when invoked MUST run the following steps:

  1. If state is not equal to held raise an ILLEGAL_STATE exception
  2. Otherwise make a request to the telephony system to resume the call. If the request is acknowledged, then set state to resuming.

When TCallControl detects that the call has being actually resumed it MUST set state to connected.

The answer method when invoked MUST run the following steps:

  1. If state is not equal to incoming or waiting raise an ILLEGAL_STATE exception
  2. Otherwise make a request to the telephony system to answer the call. If the request is acknowledged then set state to accepted.

The redirect method when invoked MUST run the following steps:

  1. If state is not equal to incoming raise an ILLEGAL_STATE exception
  2. Otherwise make a request to the telephony system to redirect the call to the number indicated in the redirectNumber parameter. If the request is acknowledged then set state to redirecting.

When TCallControl is notified that the call has been successfully redirected it MUST set state to disconnected.

Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the TelephonyCall object:

event handler event handler event type
onstatechange statechange
ondialing dialing
onalerting alerting
onaccepted accepted
onconnecting onconnecting
onconnected connected
ondisconnecting disconnecting
ondisconnected disconnected
onincoming incoming
onholding holding
onheld held
onresuming resuming
onredirecting redirecting
onerror error

Open issues

Multiparty calls have to be specified.

Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support