W3C

Web Telephony API

W3C First Public Working Draft 20 June 2013

This version:
http://www.w3.org/TR/2013/WD-telephony-20130620/
Latest published version:
http://www.w3.org/TR/telephony/
Latest editor's draft:
http://www.w3.org/2012/sysapps/telephony/
Editors:
Marcos Cáceres, Mozilla
José M. Cantera, Telefónica
Eduardo Fullea, Telefónica
Zoltan Kis, Intel
Repository:
We are on Github.
File a bug.
Commit history.

Abstract

This specification defines an API to manage telephone calls. A typical use case of the Web Telephony API is the implementation of a 'Dialer' application supporting multiparty calls and multiple telephony services. A minimal structure for call history items is also defined.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document defines a System Level API for access to telephony services, such as support for dialing phone numbers, including emergency services, multiparty (conference) calls, the means to send DTMF tone sequences, and to handle a variety of events signalling changes in the call state.

This document was published by the System Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

This is a work in progress! This specification is for review purposes only and not for implementation! For the latest updates, possibly including important bug fixes, please look at the editor's draft instead. If you find any bugs, typos, or issues please file a bug!

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

The Web Telephony API allows applications to manage interaction with telephony call signaling, but does not handle audio channels management.

An example of making a telephony call is provided below:

Example 1
var telCall = navigator.telephony.dial('+1234567890');

telCall.onactive = function(e) {
    window.console.log('Connected!');
}

telCall.ondisconnected = function(e) {
    window.console.log('Disconnected!');
    // update call history
}

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

The use cases for this specification are collected in the wiki page of this API.

The following specifications have been used for designing the Web Telephony API: for GSM the [GSM-CALL] suite, for IMS/SIP the [IMS] suite, for XMPP the [JINGLE] specification. The same API would work also for SIP and XMPP calls, except multiparty call handling, which is modeled after the cellular multiparty calls.

Future versions of this specification may add SIP and XMPP conference support.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

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.

3. 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 task source for all tasks queued in this specification is the Telephony task source.

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

The Promise interface is defined in [DOM4].

An active call is a TelephonyCall in the active state representing a connected call which is bound to the media input and output devices (e.g. microphone, speaker, tone generator). Note that a call on hold is also active from a call signaling point of view, but not bound to media input and output devices.

A telephony service exposes telephony functionality associated to a subscriber identity registered with a telephony service provider. For example, in cellular telephony a telephony service is associated to a SIM card (Subscriber Identity Module). When making a call, the identity (e.g. SIM card, associated to an Integrated Circuit Card Identifier, ICC-ID) is always provided, either explicitly in the function call, or by using a default telephony service in the implementation. The device can receive phone calls from any active telephony service, even simultaneously, in which case the user agent arbitrates the calls either by a policy, or by the user by choosing which call to accept. A telephony service can use different protocols for telephony signaling and media (e.g. GSM, CDMA, VoLTE, etc.) with the same identity. Since call states can differ depending on the protocol, the telephony call objects contain information which identifies the service and the protocol used for making the call.

A default telephony service is the telephony service that is set as default for telephony operations by the implementation.

A telephony service id uniquely identifies a telephony service together with a user identity in the system. For SIM cards, this can include the ICC-ID as service identifier. However, the MSISDN MUST NOT be used as telephony service id.

A multiparty call (also referred to as conference call) is a telephony call with multiple remote party participants, which is controlled as a single call, i.e. can be put on hold, activated, disconnected with all participants. Other calls can be joined with a multiparty call. This version supports GSM multiparty calls and CDMA 3-way calls.

A conference id uniquely identifies a multiparty call in the system and in call history.

A remote party id uniquely identifies a participant (a.k.a. remote party) in a telephony call in the given telephony service, such as a phone number.

4. Security and privacy considerations

This API must be only exposed to trusted content.

Issue 1

To be written. See bug 26.

5. Extensions to Navigator object

The TelephonyManager interface is exposed on [HTML]'s Navigator object.

partial interface Navigator {
    readonly    attribute TelephonyManager telephony;
};

5.1 Attributes

telephony of type TelephonyManager, readonly
When getting, the user agent MUST return the TelephonyManager object, which provides the ability to interface with the telephony service of the device.

6. TelephonyManager Interface

The TelephonyManager interface provides access to telephony functionality, and manages the lifecycle of the Call objects.

interface TelephonyManager : EventTarget {
    readonly    attribute Call?        activeCall;
    readonly    attribute Call[]       calls;
    readonly    attribute DOMString[]  emergencyNumbers;
    readonly    attribute DOMString[]  serviceIds;
    readonly    attribute DOMString    defaultServiceId;
    Promise       changeDefaultService (DOMString serviceID);
    TelephonyCall dial (DOMString remoteParty, optional DialParams params);
    Promise       sendTones (DOMString tones, optional ToneParams params);
    Promise       startTone (DOMString tone, optional ToneParams params);
    Promise       stopTone (optional DOMString serviceId);
                attribute EventHandler onincoming;
                attribute EventHandler oncallschanged;
                attribute EventHandler onserviceadded;
                attribute EventHandler onserviceremoved;
                attribute EventHandler onservicechanged;
};

6.1 Attributes

activeCall of type Call, readonly , nullable
When getting, the user agent MUST return a Call object representing the active call. If there is no active Call return null.
calls of type array of Call, readonly
When getting, the user agent MUST return an array, which can be empty, of Call objects managed by this objects. Note that TelephonyCall objects belonging to a multiparty call are managed by the corresponding ConferenceCall object and MUST NOT be also present in this array.
defaultServiceId of type DOMString, readonly
When getting, the user agent MUST return the DOMString that represents the id of the default telephony service.
emergencyNumbers of type array of DOMString, readonly
When getting, the user agent MUST return an array, which can be empty, of telephone numbers for the emergency services in the current geographical area.
oncallschanged of type EventHandler,
Whenever a call is added to or removed from the calls array, the user agent MUST queue a task to fire a simple event named callschanged.
onincoming of type EventHandler,
Whenever there is a new call in incoming or waiting state, the user agent MUST queue a task to fire an event named incoming of type TelephonyEvent. The call property of the event MUST be set to the TelephonyCall object controlling the incoming call.
onserviceadded of type EventHandler,
The serviceadded event of type TelephonyServiceEvent MUST be fired whenever a new telephony service is enabled in the system. The serviceId property of the event MUST contain the telephony service id of the new service. Note that compliant implementations may not be reporting such events when they occur (e.g. OTA SIM update or hot-swappable SIM cards).
onservicechanged of type EventHandler,
Handles a change of default telephony service from one to another.
onserviceremoved of type EventHandler,
The serviceremoved event of type TelephonyServiceEvent MUST be fired when an existing telephony service is disabled in the system. The serviceId property of the event MUST contain the telephony service id of the disabled service.
serviceIds of type array of DOMString, readonly
When getting, the user agent MUST return an array, which can be empty, of telephony service id's.

6.2 Methods

changeDefaultService
Provides a means to change the default telephony service used by the user agent. When invoked, the user agent runs the steps to update the default service.
Parameter Type Nullable Optional Description
serviceID DOMString A service id for a telephony service known to the user agent.
Return type: Promise
dial
Initiates a new telephony call. Returns a TelephonyCall object, which will manage the asynchronous call signaling events.
Parameter Type Nullable Optional Description
remoteParty DOMString Represents the destination number of the call.
params DialParams If set, represents the optional parameters of the call, including the telephony service to be used, and whether caller ID is hidden
Return type: TelephonyCall
sendTones
This method asynchronously emits a [DTMF] tone sequence with the platform default or specified duration and delay, in the platform default or the specified telephony service. A Promise object will be returned in order to notify the result of the request.
Parameter Type Nullable Optional Description
tones DOMString Represents the sequence of [DTMF] tones to be emitted. Its value can be any sequence of the following characters (0-9; A-D; *; #).
params ToneParams If set, represents the telephony service id to be used, the tone duration and the delay (gap) before a tone. If not set, implementations MUST use default values for these.
Return type: Promise
startTone
This method starts emitting a [DTMF] tone with the platform default or specified delay, in the platform default or the specified telephony service. A Promise object will be returned in order to notify the result of the request.
Parameter Type Nullable Optional Description
tone DOMString Represents the [DTMF] tone. Its value can be any of the following characters: 0-9; A-D; *; #.
params ToneParams If set, represents the telephony service id to be used, and the delay before a tone. The duration parameter is ignored. If not set, implementations MUST use default values for telephony service and delay.
Return type: Promise
stopTone
This method stops emitting a [DTMF] tone in the default or the specified telephony service. A Promise object will be returned in order to notify the result of the request.
Parameter Type Nullable Optional Description
serviceId DOMString
Return type: Promise

6.3 Event handlers

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

event handler event name event type short description
onincoming incoming TelephonyEvent handles incoming and waiting calls
oncallschanged callschanged simple event handles change in the calls array
onserviceadded serviceadded TelephonyServiceEvent handles a new enabled telephony service
onserviceremoved serviceremoved TelephonyServiceEvent handles a disabled telephony service
onservicechanged servicechanged TelephonyServiceEvent handles the change of default telephony service

6.4 Steps

The TelephonyManager object MUST queue a task TCallControl for each TelephonyCall or ConferenceCall object it manages, which MUST listen to any event that results in changing the call, and upon such events, follow the steps described in this specification.

The steps to update the default service are as follows:

  1. Let potential service be the first argument passed to this operation.
  2. Let promise be a new Promise object and resolver its associated resolver.
  3. Return promise and continue the following steps asynchronously.
  4. If potential service does not exactly match the identifier of any telephony service known to the user agent, run the following sub-steps and terminate this algorithm:
    1. Let error be a new DOMError object whose name is "NotFoundError".
    2. Invoke resolver's reject(value) method with error as the value argument.
  5. If potential service exactly matches the service id of the current default telephony service, run the following sub-steps and terminate this algorithm:
    1. Invoke resolver's accept(value) method with potential service as the value argument.
  6. Otherwise, run the steps to change the default service, with potential service as the telephony service id, and promise as the Promise.

The steps to change the default service are given by the following algorithm. This abstract operation takes as an argument a telephony service id and an optional Promise.

  1. Make a platform/system specific request to the underlying system to change from the current default telephony service to the one identified by service id.
  2. Possibly wait indefinately.
  3. If it's not possible (for whatever reason: timeout, security, etc.) to change the default telephony service, and if promise was passed, run the following sub steps and terminate this algorithm:
    1. Let error be a new DOMError object whose name is "NoModificationAllowedError".
    2. Call resolver's reject(value) method with error as the value argument.
  4. Otherwise, queue a task to:
    1. Change the defaultServiceId attribute to the telephony service id of the new default telephony service.
    2. If Promise was passed, invoke resolver's accept(value) method with the id of the new default service as value argument.
    3. Fire a simple event named servicechange at the telephony attribute of the navigator object.

The dial method when invoked MUST run the following steps:

  1. Create a new TelephonyCall object, referred as telCall in these steps.
  2. Set the remoteParty property of telCall to the remote party identifier specified in the remoteParty parameter.
  3. If calls array already contains a TelephonyCall object with identical remoteParty property, then an InvalidModificationError MUST be thrown.
  4. Otherwise, make a request to the telephony system to dial in the remote party identifier passed in the remoteParty parameter. Note that the value can be also an emergency number. According to the value of the hideCallerId in the params parameter, the own number is requested to be either displayed, hidden or otherwise the default system configuration to this regard is requested to be followed. The call MUST be made using the telephony service specified in the service property of the params parameter. If not specified, then the implementation MUST use the default telephony service. Even if there is no SIM card and no other telephony services are available, but emergency calls are known to be possible (e.g. because a cellular modem is present), it is considered as a default service with only emergency call capability, and the implementation MUST define a telephony service id for it. When not even emergency calls are possible (e.g. it is a purely IP based implementation and there is no cellular modem), the implementation MAY use empty string for default telephony service id, but it is encouraged that a default service is created, with the methods throwing a NotSupported error.
  5. If the request is successful, then
    1. Set the state of telCall to "dialing" value.
    2. Add telCall to the calls array.
    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.
  6. If during further steps for call connection there is an error, execute the error steps for telCall.

The sendTones method when invoked MUST run the following steps:

  1. If the ToneParams parameter specifies the serviceId to be used, then validate and use that value, otherwise use the default telephony service for sending the tones.
  2. If the ToneParams parameter specifies the tone duration, then validate and use that value, otherwise use a default value.
  3. If the ToneParams parameter specifies the tone gap, then validate and use that value, otherwise use a default value.
  4. Request from the telephony system to send the specified tones.
  5. Let promise be a new Promise object and resolver its associated resolver.
  6. Return promise to the caller and continue the following steps asynchronously.
  7. If the request to the telephony system is successful, or if the telephony system does not support feedback about the result of the request, invoke resolver's accept() method with no arguments.
  8. If the request to the telephony system is unsuccessful, invoke resolver's reject() method, with no arguments.

The startTone method when invoked MUST run the following steps:

  1. If the platform does not support long press [DTMF] tones, throw a NotSupported error and finish these steps. In this case applications may then use the sendTones method for sending [DTMF].
  2. If the ToneParams parameter specifies the serviceId to be used, then validate and use that value, otherwise use the default telephony service for sending the tones.
  3. If the ToneParams parameter specifies the tone duration, then ignore that value.
  4. If the ToneParams parameter specifies the tone gap, meaning the delay before sending the tone, then validate and use that value, otherwise use a default value.
  5. Request from the telephony system to start sending the specified tone. The tone SHOULD play until the stopTone method is called.
  6. Let promise be a new Promise object and resolver its associated resolver.
  7. Return promise to the caller and continue the following steps asynchronously.
  8. If the request to the telephony system is successful, or if the telephony system does not support feedback about the result of the request, invoke resolver's accept() method with no arguments.
  9. If the request to the telephony system is unsuccessful, invoke resolver's reject() method, with no arguments.

The stopTone method when invoked MUST run the following steps:

  1. If the platform does not support long press [DTMF] tones, throw a NotSupported error.
  2. If the provided parameters are invalid, or there is no tone playing on the specified telephony service, throw an InvalidStateError error.
  3. Otherwise, request from the telephony system to stop sending the specified tone.
  4. Let promise be a new Promise object and resolver its associated resolver.
  5. Return promise to the caller and continue the following steps asynchronously.
  6. If the request to the telephony system is successful, or if the telephony system does not support feedback about the result of the request, invoke resolver's accept() method with no arguments.
  7. If the request to the telephony system is unsuccessful, invoke resolver's reject() method, with no arguments.

Upon a new incoming or waiting call, the user agent MUST execute the following steps:

  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 active state, or otherwise set it 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 TelephonyManager object managing the call.
  6. Queue a task to fire a simple event named callschanged at the TelephonyManager object managing the call.
  7. Queue a task TCallControl to monitor call flow progress.
Issue 2

The incoming, serviceadded and serviceremoved events have to be defined according to DOM4.

The task TCallControl MUST listen to any event that results in a call disconnection, and upon such events, follow the steps described for handling disconnected calls.

6.5 DialParams Dictionary

dictionary DialParams {
    boolean   hideCallerId;
    DOMString serviceId;
};

6.5.1 Dictionary DialParams Members

hideCallerId of type boolean
Represents whether the own number is to be hidden or displayed to the remote party being called. If missing, the user agent uses the default configuration for the telephony service that initiated the call.
serviceId of type DOMString
Represents the telephony service id of the telephony service to be used when dialing.

6.6 ToneParams Dictionary

dictionary ToneParams {
    unsigned long duration;
    unsigned long gap;
    DOMString     serviceId;
};

6.6.1 Dictionary ToneParams Members

duration of type unsigned long
Represents the duration (mark) in milliseconds of the [DTMF] tones to be sent.
gap of type unsigned long
Represents the duration in milliseconds of the time gap (space) before a [DTMF] tone.
serviceId of type DOMString
Represents the telephony service id of the telephony service to be used when dialing.

7. TelephonyErrorEvent Interface

Represents an error that occured during the lifecycle of a telephony call.

interface TelephonyErrorEvent : Event {
    readonly    attribute Call     call;
    readonly    attribute DOMError error;
};

7.1 Attributes

call of type Call, readonly
When getting, the user agent MUST return the TelephonyCall object which caused the event to be fired.
error of type DOMError, readonly
When getting, the user agent MUST return the DOMError object that describes the error that occured.

8. TelephonyEvent Interface

Defines telephony events for TelephonyCall state changes, including handling incoming and waiting calls.

interface TelephonyEvent : Event {
    readonly    attribute Call call;
};

8.1 Attributes

call of type Call, readonly
When getting, the user agent MUST return the TelephonyCall that triggered the event.

9. TelephonyServiceEvent Interface

Defines a telephony event for notifying a changed telephony service.

interface TelephonyServiceEvent : Event {
    readonly    attribute DOMString serviceId;
};

9.1 Attributes

serviceId of type DOMString, readonly
When getting, the user agent MUST return the telephony service id of the telephony service that triggered the event.

10. CallHandler interface

The CallHandler interface provides common properties and event handling infrastructure that is implemented by other interfaces in this specification, e.g. TelephonyCall and ConferenceCall. It serves as an editorial aid in this specification, and has no functional utility on its own.

[NoInterfaceObject]
interface CallHandler {
    void resume ();
    void hold ();
    void disconnect ();
    readonly    attribute DOMString    callId;
    readonly    attribute DOMString    serviceId;
    readonly    attribute CallState    state;
                attribute EventHandler onerror;
                attribute EventHandler onstatechange;
};

10.1 Attributes

callId of type DOMString, readonly
When getting, the user agent MUST return the call id of the Call object, unique in the system and call history.
onerror of type EventHandler,
Event handler dispatched when there is an error during the life cycle of a call.
onstatechange of type EventHandler,
Event handler dispatched when the state changes.
serviceId of type DOMString, readonly
When getting, the user agent MUST return the telephony service id of the telephony service associated with this call.
state of type CallState, readonly
When getting, the user agent MUST return the CallState value that represents the state of for the Call.

10.2 Methods

disconnect
If invoked on a TelephonyCall, it initiates releasing of the telephony call. If invoked on a ConferenceCall, Initiates releasing the multiparty call, and each participating TelephonyCall object.
No parameters.
Return type: void
hold
Initiates putting the Call on hold.
No parameters.
Return type: void
resume
Initiates resuming a held Call.
No parameters.
Return type: void

10.3 Event handlers

The following are the event handlers that MUST be supported as attributes:

event handler event name event type short description
onstatechange statechange simple event handles any call state change
onerror error simple event handles error conditions

10.4 TelephonyCall Interface

Defines the object structure for controlling calls.

TelephonyCall implements CallHandler;

All instances of the TelephonyCall type are defined to also implement the CallHandler interface.

interface TelephonyCall : EventHandler {
    readonly    attribute DOMString?   remoteParty;
    readonly    attribute DOMString?   conferenceId;
    void           accept ();
    void           redirect (DOMString remoteParty);
    void           transfer (DOMString thirdParty);
    ConferenceCall createConference ();
                attribute EventHandler ondialing;
                attribute EventHandler onalerting;
                attribute EventHandler onaccepted;
                attribute EventHandler onconnecting;
                attribute EventHandler onactive;
                attribute EventHandler ondisconnecting;
                attribute EventHandler ondisconnected;
                attribute EventHandler onholding;
                attribute EventHandler onheld;
                attribute EventHandler onresuming;
                attribute EventHandler onredirecting;
                attribute EventHandler ontransferring;
                attribute EventHandler onjoining;
                attribute EventHandler onmultiparty;
                attribute EventHandler onsplitting;
};

10.4.1 Attributes

conferenceId of type DOMString, readonly , nullable
When getting, if this call is managed as a part of a multiparty call then the user agent MUST return the value of the conferenceId property of the ConferenceCall multiparty call to which this call is part of. Otherwise, return null.
onaccepted of type EventHandler,
Event handler called when the call state changes to "accepted" and the accepted event is dispatched.
onactive of type EventHandler,
Event handler called when the call state changes to "active" and the active event is dispatched.
onalerting of type EventHandler,
Event handler called when the call state changes to "alerting" and the alerting event is dispatched.
onconnecting of type EventHandler,
Event handler called when the call state changes to "connecting" and the connecting event is dispatched.
ondialing of type EventHandler,
Event handler called when the call state changes to "dialing" and the dialing event is dispatched.
ondisconnected of type EventHandler,
Event handler called when the call state changes to "disconnected" and the disconnected event is dispatched.
ondisconnecting of type EventHandler,
Event handler called when the call state changes to "disconnecting" and the disconnecting event is dispatched.
onheld of type EventHandler,
Event handler called when the call state changes to "held" and the held event is dispatched.
onholding of type EventHandler,
Event handler called when the call state changes to "holding" and the holding event is dispatched.
onjoining of type EventHandler,
Event handler called when the call state changes to "joining" and the joining event is dispatched.
onmultiparty of type EventHandler,
Event handler called when the call state changes to "multiparty" and the multiparty event is dispatched.
onredirecting of type EventHandler,
Event handler called when the call state changes to "redirecting" and the redirecting event is dispatched.
onresuming of type EventHandler,
Event handler called when the call state changes to "resuming" and the resuming event is dispatched.
onsplitting of type EventHandler,
Event handler called when the call state changes to "splitting" and the splitting event is dispatched.
ontransferring of type EventHandler,
Event handler called when the call state changes to "transferring" and the transferring event is dispatched.
remoteParty of type DOMString, readonly , nullable
When getting, the user agent MUST return the remote party identifier (e.g. telephone number) of the call participant. If not available (e.g. callerId has been hidden), return null.

10.4.2 Methods

accept
Accepts the incoming or waiting telephony call.
No parameters.
Return type: void
createConference
Creates a multiparty call from the current call. On cellular telephony services, this happens by initiating merging the active and held calls into a multiparty call. Using this method MUST be the only way to create a ConferenceCall object.
No parameters.
Return type: ConferenceCall
redirect
Initiates deflecting an incoming or waiting telephone call to another remote party.
Parameter Type Nullable Optional Description
remoteParty DOMString Represents the remote party to which the call is redirected.
Return type: void
transfer
Initiates transferring the call to a new call between the remote party of this call and another remote party, then disconnects the call.
Parameter Type Nullable Optional Description
thirdParty DOMString Represents the remote party to which the call is transferred.
Return type: void

10.4.3 Event handlers

The following are the event handlers MUST be supported as attributes by the TelephonyCall object:

event handler event name event type short description
ondialing dialing simple event handles call state changes to the "dialing" state
onalerting alerting simple event handles call state changes to the "alerting" state
onaccepted accepted simple event handles call state changes to the "accepted" state
onconnecting connecting simple event handles call state changes to the "connecting" state
onactive active simple event handles call state changes to the "active" state
ondisconnecting disconnecting simple event handles the call state changes to the "disconnecting" state
ondisconnected disconnected TelephonyEvent handles call state changes to the "disconnected" state
onholding holding simple event handles call state changes to the "holding" state
onheld held simple event handles call state changes to the "held" state
onresuming resuming simple event handles call state changes to the "resuming" state
onredirecting redirecting simple event handles call state changes to the "redirecting" state
ontransferring transferring simple event handles call state changes to the "transferring" state
onjoining joining simple event handles call state changes to the "joining" state
onsplitting splitting simple event handles call state changes to the "splitting" state
onmultiparty multiparty simple event handles call state changes to the "multiparty" state
Issue 3

The call state events have to be defined according to DOM4.

10.4.4 Steps

The implementation MUST follow the call state changes in the supported telephony backend(s) and networks, and MUST keep the state property updated. Since call state transitions depend on protocol, network equipment, modem, etc., the implementation MUST NOT fire error events on assumed erroneous state transitions. Applications MUST always re-synchronize any eventual internal states to the current call state reported by the telephony system. The implementation MUST NOT set the call state to any other value than specified in the descriptions of the methods of this interface.

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

  1. Queue a task to fire a simple event named statechange.
  2. Queue a task to fire a simple event named with the new value of the state attribute.

For call setup on received calls, the following call states MUST be supported in this order:

  1. "incoming"/"waiting".
  2. "accepted".
  3. "active".
Note

On received calls, telephony protocols also use a "ringing" state, set by the mobile terminal when local call alerting starts, in order to notify the remote party about the ongoing alerting (ringing can actually be e.g. a beep, ring tone, or vibration pattern). This is considered to be responsibility of implementations: if the modem expects this state to be set, implementations MUST make sure to set it. Dialer applications are not expected to set this state in the current version of the specification.

Issue 4

CDMA cannot report all these states in the expected sequence. The ‘connected’ state (i.e. when the mobile station send the Service Connect Completion Message or Connect Order, depending on whether the call is mobile originated or terminated) is immediately followed by voice media transmission – there is transition to ‘active’ before the media arrives. Therefore it should be up to the implementation to determine which events to fire and in which order. Dialer applications SHOULD be prepared to handle such cases.

For call setup on dialed calls, the following call states MUST be supported in this order:

  1. "dialing".
  2. "alerting".
  3. "active".
Note

On the telephony services which support the "connecting" call state (e.g. GSM and CDMA, for call routing, forwarding, voicemail handling etc), implementations SHOULD support this state too, between the "dialing" and "alerting" states. Dialer applications can associate the protocol with the telephony service used for the call.

Note

It is under discussion whether a system message should be propagated when a CDMA telephony call is active, since not all CDMA networks support concurrent services. Therefore, many applications will lose their data connection when the end user is in a voice call.

When a call monitoring task, previously referred to as TCallControl is notified that a dialed call is in the process of being connected, it MUST set state to "connecting".

When TCallControl is informed that the connection has been established and the call is active, it MUST set state to "active".

If there is any error during method calls, then the error steps MUST be executed.

The disconnect method when invoked on the Call object telCall, it MUST run the following steps:

  1. Set the state of telCall to "disconnecting".
  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 disconnecting at the telCall object.
  4. Request from the telephony system the disconnection of the call, then return and continue these steps asynchronously. If there is any error, the error steps MUST be executed.

Depending on the protocol, there may be restrictions on methods. For instance, GSM does not permit disconnecting a held call. Also, disconnecting a participant in a held multiparty call is not supported. In such case, the error steps MUST be executed. Also, if the controlling party disconnects in IS-41 3-way call in CDMA, then all parties are disconnected, and it is not possible for the controlling party to disconnect only one participant (that participant must choose to hang up). Therefore if the telephony service is CDMA, when invoking the disconnect() method of a TelephonyCall object participating in a ConferenceCall the error steps MUST be executed.

When TCallControl is notified of actual call disconnection of the Call object telCall, it MUST follow the next steps:

  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.

The param property of the disconnected event MUST be set to the DisconnectReason, if available, or otherwise it MUST be set to null. At least the following values MUST be supported for the disconnect reason: "local", "remote" and "network". The rest of the DisconnectReason values SHOULD be supported.

The hold method when invoked MUST run the following steps:

  1. If state is not equal to active, then an InvalidStateError MUST be thrown.
  2. Otherwise make a request to the telephony system to hold the call.
  3. Return, and continue these steps asynchronously.
  4. 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", then an InvalidStateError MUST be thrown.
  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 "active".

The accept method when invoked MUST run the following steps:

  1. If state is not equal to "incoming" or "waiting", then an InvalidStateError MUST be thrown.
  2. Otherwise make a request to the telephony system to accept 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" or "waiting", then an InvalidStateError MUST be thrown.
  2. Otherwise make a request to the telephony system to redirect the call to the number indicated in the remoteParty parameter, return, and continue these steps asynchronously.
  3. If the request is acknowledged, then set state to "redirecting".
  4. When TCallControl is notified that the call has been successfully redirected it MUST set state to "disconnected".
Note

The telephony service in use must have the call deflection feature enabled in order that this method could succeed. For instance, in GSM, the Call Deflection supplementary service must be active.

The transfer method when invoked MUST run the following steps:

  1. If state is not equal to "active" or "held", then an InvalidStateError MUST be thrown.
  2. Otherwise make a request to the telephony system to transfer the call to the number indicated in the thirdParty parameter. Note that in GSM this requires putting the current call on hold, dialing a new call to the third party, then initiating the call transfer procedure. If there is an error, the original call MUST be resumed and the error steps MUST be executed without modifying the call state. If the request is acknowledged, then set state to "transferring".
  3. When TCallControl is notified that the call has been successfully transferred and the original call is disconnected, it MUST set state to "disconnected".
Note

The telephony service in use must have the call transfer feature enabled in order that this method could succeed. For instance, in GSM, the Call Transfer supplementary service must be active.

The createConference method MUST run the following steps when invoked on a TelephonyCall object, referred as telCall in these steps:

  1. Set the state of telCall to "joining".
  2. Then, in cellular telephony services, make a request to the telephony system to join the active and held calls into a multiparty call.
  3. If one of the calls is already a ConferenceCall object, use it as confCall in these steps.
  4. Otherwise create a new ConferenceCall object with a unique conference id, named confCall.
  5. Set the state of confCall to "joining".
  6. Return the confCall object, and continue these steps asynchronously.
  7. If the request to the telephony system is successful,
    1. set the conferenceId property of the participating calls to the unique identifier generated for the multiparty call confCall.
    2. Add the calls participating in the multiparty call to the calls property of the confCall object, remove them from the calls array of the TelephonyManager object, and set their state to 'multiparty'.
    3. Add the confCall object to the calls array of the TelephonyManager object.
    4. Set the state of confCall to "active".
    5. Queue a task to fire a simple event named participantadded at confCall. object
    6. Follow the state changes of confCall through the state change events.
    7. If there is any error during the method call, then the error steps MUST be executed on the telCall object.
Inbound Call State Diagram
Fig. 1 The figure depicts the most usual state transitions for received calls.
Inbound Call State Diagram
Fig. 2 The figure depicts the most usual state transitions for dialed calls.

11. ConferenceCall Interface

Describes the object controlling multiparty calls, and managing the TelephonyCall objects participating in the multiparty call.

ConferenceCall implements CallHandler;

All instances of the ConferenceCall type are defined to also implement the CallHandler interface.

interface ConferenceCall : EventTarget {
    readonly    attribute DOMString       conferenceId;
    readonly    attribute TelephonyCall[] calls;
    void split (TelephonyCall participantCall);
                attribute EventHandler    onparticipantadded;
                attribute EventHandler    onparticipantremoved;
                attribute EventHandler    onjoining;
                attribute EventHandler    onactive;
                attribute EventHandler    onsplitting;
                attribute EventHandler    onholding;
                attribute EventHandler    onheld;
                attribute EventHandler    onresuming;
                attribute EventHandler    ondisconnecting;
                attribute EventHandler    ondisconnected;
};

11.1 Attributes

calls of type array of TelephonyCall, readonly
When getting, the user agent MUST return the array of TelephonyCall objects managed by the multiparty call object.
conferenceId of type DOMString, readonly
When getting, the user agent MUST return the conference identifier unique in the system and in call history. It MUST NOT be the empty string.
onactive of type EventHandler,
Event handler called when the call state changes to "active" and the active event is dispatched.
ondisconnected of type EventHandler,
Event handler called when the call state changes to "disconnected" and the disconnected event is dispatched.
ondisconnecting of type EventHandler,
Event handler called when the call state changes to "disconnecting" and the disconnecting event is dispatched.
onheld of type EventHandler,
Event handler called when the call state changes to "held" and the held event is dispatched.
onholding of type EventHandler,
Event handler called when the call state changes to "holding" and the holding event is dispatched.
onjoining of type EventHandler,
Event handler called when the call state changes to "joining" and the joining event is dispatched.
onparticipantadded of type EventHandler,
Event handler called when a new participant has been added to the conference call as a result of the createConference method, and the participantadded event is dispatched.
onparticipantremoved of type EventHandler,
Event handler called when a participant has been removed from the conference call as the result of the split method, or because the participant call was disconnected, and the participantadded event is dispatched.
onresuming of type EventHandler,
Event handler called when the call state changes to "resuming" and the resuming event is dispatched.
onsplitting of type EventHandler,
Event handler called when the call state changes to "splitting" and the splitting event is dispatched.

11.2 Methods

split
Initiates splitting the specified participant TelephonyCall object, activate it and put this multiparty call on hold.
Parameter Type Nullable Optional Description
participantCall TelephonyCall Represents the TelephonyCall object of the call participant to be split from the multiparty call.
Return type: void

11.3 Steps

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

multiparty call state string value description
joining 'joining' The multiparty call is being created, or joined with another call
active "active" The multiparty call is ongoing
splitting 'splitting' A call is being split from a multiparty call.
holding 'holding' The call is being put on hold
held 'held' The call has been put on hold
resuming 'resuming' The call, which was on hold, is being resumed
disconnecting 'disconnecting' A request to disconnect the call has been made and it is progressing
disconnected 'disconnected' The multiparty call has been disconnected and this object is invalid for call control. In this final state, the implementation MUST throw an ILLEGAL_STATE exception when any method call is attempted.

For multiparty calls, the implementation MUST generate a unique identifier stored in the callId property. In GSM, the callId of any participating call could be used in a multiparty operation, and the telephony network will reply with using the same value. But for forward compatibility reasons, the implementation MUST generate a separate callId value for the multiparty call, which MUST be unique in the system and the local call history. For GSM multiparty functionality, The implementation MUST map this to an appropriate transaction identifier accepted by the telephony service. Also, the transaction identifiers received from the network MUST be mapped back by the implementation to the unique conference call identifier of the multiparty call.

The split method when invoked MUST run the following steps:

  1. If the provided participantCall does not identify a valid TelephonyCall object which is part of this multiparty call, then an InvalidModificationError MUST be thrown.
  2. Otherwise, set the state of the participantCall and that of this ConferenceCall object to "splitting".
  3. Make a request to the telephony system to split the call participant from the multiparty call.
  4. Return, and continue these steps asynchronously.
  5. If the request was successful, the telephony system will put the multiparty call on hold and activate the split call. The implementation MUST follow the state transitions on the calls as described in this specification.
  6. Reset the conferenceId of the split call to null.
Note

In CDMA, only 3-way calling is supported. This is an IS-41 CN limitation (see Network Interworking between GSM-MAP and TIA-41, 3GPP2 document, p. 1-50 provides a comparison of multiparty call and 3-way call.

11.4 Event handlers

The following are the event handlers MUST be supported as attributes by the ConferenceCall object:

event handler event name event type short description
onactive active simple event handles call state changes to the "active" state
ondisconnecting disconnecting simple event handles the call state changes to the "disconnecting" state
ondisconnected disconnected TelephonyEvent handles call state changes to the "disconnected" state
onholding holding simple event handles call state changes to the "holding" state
onheld held simple event handles call state changes to the "held" state
onresuming resuming simple event handles call state changes to the "resuming" state
onjoining joining simple event handles call state changes to the "joining" state
onsplitting splitting simple event handles call state changes to the "splitting" state

12. CallState enum

enum CallState {
    "dialing",
    "connecting",
    "alerting",
    "active",
    "incoming",
    "waiting",
    "accepted",
    "holding",
    "held",
    "resuming",
    "redirecting",
    "transferring",
    "disconnecting",
    "disconnected",
    "joining",
    "multiparty",
    "splitting"
};
Enumeration description
dialing An outbound call that has been dialed and is being connected.
connecting A request to establish the call has been made and it is progressing.
alerting The destination number has been reached and alerting is taking place.
active The call is ongoing.
incoming An incoming call is being received whilst no other call is progressing.
waiting An incoming call that has been received whilst there was another call progressing, and the call waiting service is active.
accepted An incoming call has been accepted and is being connected.
holding The call is being put on hold.
held The call has been put on hold.
resuming The call, which was on hold, is being resumed.
redirecting The call is being redirected to another remote party from the same telephony service.
transferring The call is being transferred to another remote party from the same telephony service.
disconnecting A request to disconnect the call has been made and it is progressing.
disconnected The call has been disconnected and this object is invalid for call control. In this final state, the implementation MUST throw an ILLEGAL_STATE exception when any method call is attempted.
joining The call is being joined with another call to become a multiparty call.
multiparty The call is locked in a ConferenceCall object and MUST NOT be managed any more using this object. While in this state, the implementation MUST throw an ILLEGAL_STATE exception when any method call is attempted.
splitting The call is being split from a multiparty call.

Some of these states are soft states, that is, transitory states in which the application is placed after making a request to the telephony system and until it is completed. For instance the application remains in "holding" state since it invokes the hold() method and until the telephony system actually holds the call. In some implementations these soft states can be skipped. The following are the soft states defined by this specification: "accepted", "disconnecting", "holding", "resuming".

On the contrary, hard states MUST be supported by the implementation: "dialing", "alerting", "active", "disconnected", "incoming", "waiting", "held". For calls participating in multiparty calls, the following additional call states MUST be supported: "joining", "splitting", "multiparty". For call transfer functionality, the additional "transferring" state MUST be supported.

13. CallHistoryEntry Interface

This section is non-normative.

This interface describes the minimum set of properties which SHOULD be supported for call history entries. For multiparty call there MUST be a separate CallHistoryEntry object for each call participant, sharing the same value for the conferenceId property.

Note

It is up the the implementations and applications how to store and access call history. This document only specifies the minimum content of the data to be saved.

[NoInterfaceObject]
interface CallHistoryEntry {
    readonly    attribute DOMString          remoteParty;
    readonly    attribute DOMString          serviceId;
    readonly    attribute DOMString?         conferenceId;
    readonly    attribute Date               startTime;
    readonly    attribute unsigned long long duration;
    readonly    attribute CallDirection      direction;
    readonly    attribute DisconnectReason?  disconnectReason;
    readonly    attribute boolean            emergency;
};

13.1 Attributes

This section is non-normative.

conferenceId of type DOMString, readonly , nullable
When getting, the user agent MUST return the conference id of the call, if the call has participated in a multiparty call. Otherwise, return null. string.
direction of type CallDirection, readonly
When getting, the user agent MUST return the CallDirection.
disconnectReason of type DisconnectReason, readonly , nullable
When getting, the user agent MUST return the DisconnectReason if available, or return null otherwise.
duration of type unsigned long long, readonly
When getting, the user agent MUST return the duration of the call expressed in milliseconds.
emergency of type boolean, readonly
When getting, the user agent MUST return true if the call was an emergency call, or false otherwise.
remoteParty of type DOMString, readonly
When getting, the user agent MUST return the remote party identifier (e.g. telephone number) of the call participant.
serviceId of type DOMString, readonly
When getting, the user agent MUST return the telephony service id of the telephony service used for the call.
startTime of type Date, readonly
When getting, the user agent MUST return the starting time of the call, measured from when the call is in "active" state.

14. DisconnectReason enum

enum DisconnectReason {
    "local",
    "remote",
    "network",
    "busy",
    "rejected",
    "redirected",
    "unreachable",
    "no-answer",
    "network-unreachable",
    "barred",
    "no-service",
    "invalid-number"
};
Enumeration description
local The call was disconnected by the user, or the device, and no more specific reason is known.
remote The call was disconnected by the remote party, and no more specific reason is known.
network The call was disconnected by the network, and no more specific reason is known.
busy The call was disconnected by the network, because the remote party was busy.
rejected The call was disconnected because the remote party rejected the call.
redirected The call has been redirected to another subscriber.
unreachable The call was disconnected by the network, because the remote party was unreachable by the network.
no-answer The call was disconnected by the network, because the remote party has not answered and the call has timed out.
network-unreachable The call was disconnected because the network was unreachable.
barred The call was disconnected because it was barred.
no-service The call was not made because there is no telephony service set up and enabled (e.g. no SIM card).
invalid-number The call was disconnected by the network, because the remote party identifier was invalid.

15. CallDirection enum

enum CallDirection {
    "dialed",
    "received",
    "missed",
    "missed-new"
};
Enumeration description
dialed The call has been dialed.
received The call has been received.
missed The call has been missed.
missed-new The call was a missed call not seen yet by the user.

16. Call typedef

typedef (TelephonyCall or ConferenceCall) Call;

17. Error Steps

If there is any error during the method calls which is not handled by exceptions, the following steps MUST be run:

  1. Set the error property of the CallHandler object appropriately
  2. queue a task to fire a simple event named error at the CallHandler object.

The error name, together with the call state determine the error condition. All DOMError error names are supported, out of which the following names MUST be used with the semantics described here:

Name Description
InvalidStateError The call state is invalid, or the an attempted operation conflicts with the call state in the implementation of the telephony modem and middleware
InvalidModificationError The attempted operation conflicts with the call state or other constraints in the implementation, for instance attempting to disconnect a held call in a GSM network.
NetworkError There was a telephony network error during the operation
TimeoutError The attempted operation timed out
NotSupportedError The attempted operation is not supported by the implementation, or the telephony network. This includes cases when a needed network feature (such as a supplementary service like Call Transfer) is not enabled.
SecurityError The attempted operation is not permitted.

18. Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support, especially to Ben Turner and Jonas Sicking, the authors of the B2G WebTelephony API. Also, thanks to Denis Kenzior (ofono maintainer) and Oleg Zhurakivskyy of Intel Open Source Technology Center, and many others for their advice and support.

A. References

A.1 Normative references

[DTMF]
Q.23 : Technical features of push-button telephone sets. 1 November 1988. In force. URL: http://www.itu.int/rec/T-REC-Q.23/en
[GSM-CALL]
Bruno Landais. GSM TS 23.018 Basic call handling. 28 April 1999. Technical realization. URL: http://www.3gpp.org/ftp/Specs/html-info/23018.htm
[HTML]
Ian Hickson. HTML. Living Standard. URL: http://www.whatwg.org/specs/web-apps/current-work/
[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[IMS]
Thomas Towle. IP Multimedia Subsystem (IMS). 14 March 2002. Stage 2. URL: http://www.3gpp.org/ftp/Specs/html-info/23228.htm
[JINGLE]
Scott Ludwig; Joe Beda; Peter Saint-Andre; Robert McQueen; Sean Egan; Joe Hildebrand et al. XEP-0166: Jingle. 23 December 2009. Draft Standard. URL: http://xmpp.org/extensions/xep-0166.html
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/

A.2 Informative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/dom/