6.1 Telephony service

A telephony network is the infrastructure providing telephony functionality in a given geographical area, to which the device running the user agent is registered with at the point of operation.

A subscriber identity identifies and authenticates the user in the telephony network. In cellular telephony, subscriber identity is associated with the SIM card (Subscriber Identity Module). A given subscriber identity can be used in different, but interoperable telephony networks.

A telephony provider is the company operating the telephony network. A telephony provider can have multiple telephony networks.

A telephony modem is the software and hardware entity which implements the telephony protocols needed for interacting with the telephony networks, and which exposes an API which is used for implementing this API specification. A modem can be local to the device, or can be a remote modem, used e.g. via a paired Bluetooth device.

A telephony service is an abstract concept used in this API to denote the tuple of a given subscriber identity, and a given telephony modem. If any of these elements is changed, it means a different telephony service. Note that when a device is moving, and eventually changes the telephony network, it continues to see the same telephony service. A telephony service can use different protocols for telephony signaling and media (e.g. GSM, CDMA, VoLTE, etc.) with the same subscriber identity. There may be multiple SIM cards registered with the same provider, which will map to different telephony services.

Note the difference between dual-SIM and multiple-SIM card use cases. In dual-SIM use case the subscriber has two identities, which both can be active in the same time, i.e. could make and receive calls. In the multiple SIM card use case the subscriber has multiple identities, but only one can be active at a given time. These constraints are not exposed by this API, and implementations are expected to encapsulate them.

6.2 Telephony service id

A user agent can access zero or more telephony services. Each telephony service has a unique telephony service id at any given moment, but it is not required to uniquely identify services in call history. In other words, the identifiers MAY be reused as services appear and disappear. Service identifiers SHOULD NOT be saved in call history, only displayable service names.

Access to a telephony service by any origin is restricted by a security policy. See the Security and privacy considerations section for more details.

It is strongly RECOMMENDED that implementations do not use use the MSISDN as the telephony service id. The MSISDN cannot guarantee uniqueness. For telephony services that make use of a SIM card, it is RECOMMENDED that the ICC-ID is used for the service identifier. For reducing fingerprinting, implementations SHOULD choose to use opaque UUID's or SHA signatures as service identifiers, associated in the implementation to the internal service identifiers such as ICC-ID.

6.3 Selected telephony service

The selected telephony service is the telephony service that is used as default for the origin for the methods of this API.

Implementations are not required to initialize a selected service at startup. Instead, clients of this API may choose the preferred moment of initializing the telephony system by invoking the navigator.telephony.service.getServices() (if implemented) or the navigator.telephony.getCalls(), or the navigator.telephony.dial() methods.

If there is no selected telephony service set for the origin, the user agent SHOULD use the underlying system's default telephony service, if available. On implementations that have access to a hardware modem, regulations require supporting emergency number dialing from PIN dialog or dialer interface even in the absence of a SIM card.

6.4 Telephony call

A telephony call means a connected communication link between two or more call participants in a given a telephony service. From an application's point of view, a telephony call is an object which exposes properties and methods to monitor and control telephony calls. A telephony call involving more than two parties are referred to as a conference call or a multiparty call.

6.5 Remote party identifier

A remote party id, e.g. as a phone number, uniquely identifies a remote participant in a telephony call in the given telephony service.

6.6 Outbound and inbound call

Telephony calls initiated by the user using a telephony service in the system is an outbound call. Conversely, a telephony call from a remote party is an inbound call.

6.7 Call identifier

Every telephony call has a call id, which is a string that uniquely identifies the call among the other calls in progress. It is not required that the call id be unique across call history. Clients SHOULD NOT save the call id in call history, but SHOULD maintain their own id space, e.g. using start time and remote party information.

6.8 Call state

A call state represents the state of interaction between a telephony service, the user agent, and one or more remote parties. In the process of establishing and maintaining a connection between multiple parties, a telephony call transitions through various call states. A telephony call is always in a defined call state, which can only be changed by using methods of this API, or by the telephony service.

in GSM, there are 3 types of call states:

• GSM TS 04.08 defines call control states,
• GSM TS 04.83 defines call hold states, and
• GSM TS 24.084 defines auxiliary states associated with a multiparty call.

Instead of using a 3-dimensional call state space, this API uses a one dimensional call state model, in which call states map to valid combinations in of 3-dimensional states, and are able to describe valid state transitions.

6.9 Active call

An active call is a telephony call 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 connected from a call signaling point of view, but it is not bound to media input and output devices.

6.10 Conference call

A conference call is a telephony call with multiple remote party participants. The way conference calls are handled are quite different depending on the telephony protocol.

Creating GSM multiparty calls involve the following user interaction:

1. dial the first number
2. when the call is active, put the call on hold
3. dial the second number
4. when the second call is active, press the 'Conference' button
5. optionally repeat the steps so far to add more calls
6. any participating call can be split from the conference call for private chat, during which the conference call is put on hold
7. during private chat, it is possible to re-merge the call into the conference call using the same procedure as described from step 2.
8. disconnecting a GSM conference call will disconnect all member calls.

In CDMA, only a limited form of conference call is supported, called 3-way call, which is usually mapped to multiple presses of the 'Call' button, which in background uses modem AT commands (ATD, ATH and Flash) to achieve the desired action. Handling 3-way calls involve the following user interactions:

1. dial the first number (involves the ATD command)
2. when the call is active, dial the second number (by sending a Flash command with the second number), which automatically puts the first call on hold
3. when the second call is active, press the 'Call' button to make 3-way call (by sending a Flash command)
4. while the 3-way call is active, press the 'Call' button to disconnect the second call (which sends a Flash command
5. while the 3-way call is active, any incoming call SHOULD be rejected
6. while the 3-way call is active, pressing 'Hangup' (ATH command) will disconnect all calls.

The common way to support these user interactions by this API, there is possible programmatic support for the following actions:

1. dial the first call by calling the dial() method
2. dial the second call, which puts the first call on hold
3. create the conference call from the held and active calls by calling the createConference() method
4. disconnecting the second call works from both CDMA and GSM, by calling the disconnect() method on the second call object
5. disconnecting any other than the last call will work in GSM, but will hang up all calls in CDMA. The last call can be separately disconnected also in CDMA.

This API has been designed so that conference calls could be controlled using the same type object as with a single telephony call.

Every conference call has a conference id that uniquely identifies a conference call in the system.

8.1 The telephony attribute

When getting the telephony attribute, the user agent MUST return the TelephonyManager object, which provides telephony related functionality.

10.1 CallState enum

Within the API, the call states are represented by the CallState enum.

enum CallState {
    "dialing",
    "connecting",
    "alerting",
    "ringing",
    "active",
    "conference",
    "incoming",
    "waiting",
    "accepted",
    "held",
    "disconnected",
    "holding",
    "resuming",
    "redirecting",
    "transferring",
    "disconnecting"
};

The meaning of the call states referenced in this API is the following:

dialing

An outbound call is being dialed by a telephony service.

connecting

A request to establish the outbound call has been made and it is progressing. This state is skipped for CDMA calls. In this API it is also used as an initial state for TelephonyCall objects controlling conference calls, when created.

alerting

The destination number has been reached and alerting is taking place in an outbound call.

ringing

An inbound call is locally alerting (by beep, vibration pattern, ringing, or by other means), and the network can notify the remote party with the alerting state.

active

The call is connected and media channels are attached.

conference

The call is active, i.e. connected and media channels are attached, as part of a conference call.

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 by the remote party and is being connected.

held

The call has been put on hold by the network.

disconnected

The call has been disconnected by the network and this object is invalid for call control.

holding

The call is being put on hold.

resuming

The call, which was on hold, is being resumed.

redirecting

The call is being redirected (deflected) to another remote party.

transferring

The call is being transferred to another remote party.

disconnecting

A request to disconnect the call has been made and it is progressing.

splitting

The call is being split from a multiparty call.

10.2 Call state reason

The call state reason is used primarily for the disconnected state, known as the disconnect reason. In this API the disconnection reasons are represented by the DisconnectReason enum.

enum DisconnectReason {
    "local",
    "remote",
    "network",
    "busy",
    "rejected",
    "redirected",
    "unreachable",
    "no-answer",
    "network-unreachable",
    "barred",
    "no-service",
    "invalid-number"
};

10.3 Call state transitions

Since call state transitions depend on protocol, network equipment, modem, etc., the implementation SHOULD always re-synchronize any eventual internal states to the current call state reported by the telephony system. The implementation SHOULD NOT set the call state to any other value than specified in the descriptions of the methods of this interface.

10.3.1 Inbound call state transitions

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.

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

1. "incoming" or "waiting"
2. "accepted"
3. "active".

Note

On received calls, telephony protocols use the "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). If the modem expects this state to be set, implementations SHOULD make sure to set it.

Note

CDMA cannot report all these states in the expected sequence. The ‘connected’ network 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 no 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 need to be prepared to handle such cases.

10.3.2 Outbound call state transitions

For making a call, the telephony service transitions through the following states in order. Errors can occur at each state, which are handled by the telephony network, and may result in the call becoming disconnected:

1. dialing
2. [connecting]
3. alerting
4. 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.

10.4 TelephonyCall Interface

Defines the object structure for controlling calls, including conference calls.

interface TelephonyCall {
    readonly    attribute DOMString?          callId;
    readonly    attribute DOMString?          conferenceId;
    readonly    attribute DOMString?          remoteParty;
    readonly    attribute DOMString           serviceId;
    readonly    attribute CallState           state;
    readonly    attribute DOMString           stateReason;
    readonly    attribute TelephonyTechnology technology;
    Promise accept ();
    Promise hold ();
    Promise resume ();
    Promise disconnect ();
    Promise deflect (DOMString remoteParty);
    Promise split ();
};

enum TelephonyTechnology {
    "gsm",
    "cdma",
    "edge",
    "umts",
    "hspa",
    "lte"
};

10.5 The CallManager Interface

The CallManager interface provides access to telephony functionality related to given telephony services, and manages the lifecycle of the TelephonyCall objects. A TelephonyCall object can be created in the following ways:

• by the dial() method, returned as a parameter to the accept() method of the returned Promise object, as explained in the dialing steps.
• by the createConference() method, returned as a parameter to the accept() method of the returned Promise object, as explained in the conference creation steps. The same object will be received as a property to the TelephonyCallStateEvent corresponding to the 'connecting'' state.
• when the system notifies the user agent about an inbound call, the corresponding TelephonyCall object is created and passed as a property exposed in the TelephonyCallStateEvent event which is fired at the CallManager object navigator.telephony. This is explained at the inbound call steps.
• received as a property to the TelephonyCallStateEvent event.

interface CallManager {
    readonly    attribute TelephonyCall? activeCall;
    Promise getCalls ();
    Promise dial (DOMString remoteParty, DialOptions options);
    Promise transfer ();
    Promise createConference ();
    Promise getParticipantCalls (DOMString conferenceId);
                attribute EventHandler   oncallstatechange;
                attribute EventHandler   onactivecallchange;
};

interface TelephonyCallStateEvent : Event {
    readonly    attribute TelephonyCall call;
};

11.1 The sendTones() method

The sendTones() method requests a telephony service emit one or more [DTMF] tones.

dictionary ToneOptions {
             unsigned long duration;
             unsigned long gap;
};

When the sendTones() method is invoked, the user agent MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. If there is no selected telephony service,then invoke resolver's reject(value) method with the value argument set to a new DOMError object whose name is set to "NoModificationAllowedError", and terminate these steps.
3. Return promise to the caller and continue the following steps asynchronously.
4. If the ToneOptions parameter specifies the tone duration, then validate and use that value, otherwise use a default value.
5. If the ToneOptions parameter specifies the tone gap, then validate and use that value, otherwise use a default value.
6. Request from the telephony system to send the specified tones.
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.

11.2 The startTone() method

The startTone() 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.

When the startTone method is invoked, the user agent MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. If there is no selected telephony service, then invoke resolver's reject(value) method with the value argument set to a new DOMError object whose name is set to "NoModificationAllowedError", and terminate these steps.
3. Return promise to the caller and continue the following steps asynchronously.
4. If the platform does not support long press [DTMF] tones or starting tones, then invoke resolver's reject(value) method with the value argument set to a new DOMError object whose name is set to "NotSuppoertedError", and terminate these steps. In this case applications may then use the sendTones method for sending [DTMF].
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.

11.3 The stopTone() method

The stopTone() method stops emitting a [DTMF] tone in the selected telephony service. When invoked, the user agent MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. If there is no selected telephony service, then invoke resolver's reject(value) method with the value argument set to a new DOMError object whose name is set to "NoModificationAllowedError", and terminate these steps.
3. Return promise to the caller and continue the following steps asynchronously.
4. If the platform does not support long press [DTMF] tones or starting tones, then invoke resolver's reject(value) method with the value argument set to a new DOMError object whose name is set to "NotSupportedError", and terminate these steps.
5. Otherwise, request from the telephony system to stop sending the specified tone.
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.

12.1 Event handlers

The following are the event handlers implemented by the EmergencyManager interface.

When emergency numbers have changed, the changed event of type Event MUST be fired at the object implementing this interface. The applications SHOULD read the emergency numbers by the getEmergencyNumbers() method.

12.2 The getEmergencyNumbers() method

When the getEmergencyNumbers() method is invoked, the user agent MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. Return promise and continue the following steps asynchronously.
3. make a request to the underlying telephony system to provide the list of emergency numbers from the selected telephony service, and wait for response.
4. If it's not possible to retrieve the list of telephony service identifiers for whatever reason: timeout, security, etc., then 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.
5. Otherwise, combine the emergency numbers into a sequence of distinct DOMString strings, and queue a task to invoke resolver's accept(value) method with the sequence of emergency numbers in the current geographical area, as the value argument. The list can be empty.

13.1 Threats

The following list of threats should be considered by the implementer. Note that these are not given in any order.

• The API could be used by a malicious application to deny other system applications access to the device's telephony services, creating an availability problem. This is a safety, as well as security, concern.
• The API could be used by a malicious application as part of a distributed denial of service attack, making frequent calls to a remote call system such as an emergency response number.
• The API could be used by an application to list the telephone numbers that the end user has called and is, at any time, calling. This information ought to be considered private, and could also be used as part of a social engineering attack, or for identity theft.
• The API could be used to make unwanted calls to premium-rate telephone numbers. A malicious application could use this to earn money at the user's expense. Similarly, this API could be misused to enroll the user into a premium-rate calling service, which would then charge the end user when calls are received.
• The API could be used to make unwanted advertising calls, in a similar manner to spam email campaigns. When combined with access to the user's contact list, this would be both expensive and embarassing for the user, and could result in their telephony service being terminated by the network operator.
• The API could be used by a malicious application to make telephone calls impersonating the end user, or as part of a process to defeat a two-factor authentication system.
• A poorly implemented application could misuse this API to make unnecessary or unexpected calls, costing the user money or embarassing them.
• This API could be used to call a number other than the one that the user was expecting, routing calls to an unknown man-in-the-middle. This could be used to eavesdrop on the user. When used in combination with recordings from the microphone, this API could be used to covertly survey the end user.
• This API could be used to send USSD messages to the service provider and invoke functions such as wiping the handset or accessing security settings.
• The API could be misused to access the user's voicemail recordings.
• The API could be misused as part of a DDoS attack on an operator or service provider, flooding the network with calls at certain times.
• The API could cost the end user money by making outgoing calls when the user is roaming, or on an expensive network.

13.2 Mitigations

The following mechanisms may be employed to help an implementer mitigate the threats outlined in the previous section.

• The user agent should only expose this API to privileged applications, as defined in the Runtime and Security Model.
• The user agent should only expose this API to applications which were distributed by an institution that the handset recognises as a valid source. For example, the API might only be accessible to applications distributed by the handset manufacturer.
• All applications with access to this API should be reviewed before they are made available. A mechanism for remote update of applications with access to this API should be provided to allow for identified security issues to be fixed.
• The user agent should maintain the integrity of any application with access to this API when initially downloaded, as well as when it is stored offline.
• The user agent should only expose this API to downloaded, offline applications which are not modifiable by external web servers. A restrictive content security policy should be used to enforce that application with external content (such as scripts) cannot access this API.
• The API implementation should have different behaviour when used with premium-rate numbers. Accessing premium-rate numbers may require an additional permission to be listed in the manifest, a different (or additional) warning to be displayed to users, or place an additional requirement on the valid distributors of the application. It is up to the implementing user agent to identify whether a remote party identifier is premium-rate or not.
• The API implementation should have different behaviour when the user is roaming on a network with a different (less favourable) service-level agreement. For example, presenting a different warning to the user, or denying access to this API from certain applications altogether.
• User consent must be captured when a call is made. For example, the user must press a 'dial' button, or equivalent, before the call is placed. The user must also be shown the recipients of the call, and the numbers that have and will be dialled as part of placing it.
• It should be obvious, visually, when a call is being invoked, is in progress, and has ended. This should be visible to the end user and it must not be possible for applications to hide or obscure this indicator.
• The user agent should introduce rate limiting to prevent an application from making too many calls in too short a period of time.

13.3 User interaction guidelines

Implementations SHOULD make sure the phone calls are controllable by the user at any point in time while the call is active.