Web Telephony API

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.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.

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.

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.6 ToneParams Dictionary

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

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.1 Attributes

call of type Call, readonly

When getting, the user agent MUST return the TelephonyCall that triggered the event.

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.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:

10.4 TelephonyCall Interface

Defines the object structure for controlling calls.

TelephonyCall implements CallHandler;

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.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.

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:

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.

11.4 Event handlers

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