Added in API level 23

Summary: Nested Classes | Constants | Methods | Inherited Methods

Call

Kotlin |Java

public final class Call
extends Object

java.lang.Object
↳	android.telecom.Call

Represents an ongoing phone call that the in-call app should present to the user.

Summary

Nested classes
`class`	`Call.Callback` Defines callbacks which inform the `InCallService` of changes to a `Call`.
`class`	`Call.Details`
`class`	`Call.RttCall` A class that holds the state that describes the state of the RTT channel to the remote party, if it is active.

Constants
`String`	`AVAILABLE_PHONE_ACCOUNTS` This constant was deprecated in API level 29. Use the list from `EXTRA_SUGGESTED_PHONE_ACCOUNTS` instead.
`String`	`EVENT_CLEAR_DIAGNOSTIC_MESSAGE` Event reported from the telecom framework when a diagnostic message previously raised with `EVENT_DISPLAY_DIAGNOSTIC_MESSAGE` has cleared and is no longer pertinent.
`String`	`EVENT_DISPLAY_DIAGNOSTIC_MESSAGE` Event reported from the Telecom stack to report an in-call diagnostic message which the dialer app may opt to display to the user.
`String`	`EXTRA_ASSERTED_DISPLAY_NAME` String value indicating the asserted display name reported via ImsCallProfile#EXTRA_ASSERTED_DISPLAY_NAME.
`String`	`EXTRA_DIAGNOSTIC_MESSAGE` `CharSequence` extra used with `EVENT_DISPLAY_DIAGNOSTIC_MESSAGE`.
`String`	`EXTRA_DIAGNOSTIC_MESSAGE_ID` Integer extra representing a message ID for a message posted via `EVENT_DISPLAY_DIAGNOSTIC_MESSAGE`.
`String`	`EXTRA_IS_BUSINESS_CALL` Boolean indicating that the call is a verified business call.
`String`	`EXTRA_IS_SUPPRESSED_BY_DO_NOT_DISTURB` Extra key intended for `InCallService`s that notify the user of an incoming call.
`String`	`EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS` Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC) when the last outgoing emergency call was made.
`String`	`EXTRA_SILENT_RINGING_REQUESTED` Extra key used to indicate whether a `CallScreeningService` has requested to silence the ringtone for a call.
`String`	`EXTRA_SUGGESTED_PHONE_ACCOUNTS` Key for extra used to pass along a list of `PhoneAccountSuggestion`s to the in-call UI when a call enters the `STATE_SELECT_PHONE_ACCOUNT` state.
`int`	`REJECT_REASON_DECLINED` Reject reason used with `reject(int)` to indicate that the user is rejecting this call because they have declined to answer it.
`int`	`REJECT_REASON_UNWANTED` Reject reason used with `reject(int)` to indicate that the user is rejecting this call because it is an unwanted call.
`int`	`STATE_ACTIVE` The state of a `Call` when actively supporting conversation.
`int`	`STATE_AUDIO_PROCESSING` The state of a call that is active with the network, but the audio from the call is being intercepted by an app on the local device.
`int`	`STATE_CONNECTING` The initial state of an outgoing `Call`.
`int`	`STATE_DIALING` The state of an outgoing `Call` when dialing the remote number, but not yet connected.
`int`	`STATE_DISCONNECTED` The state of a `Call` when no further voice or other communication is being transmitted, the remote side has been or will inevitably be informed that the `Call` is no longer active, and the local data transport has or inevitably will release resources associated with this `Call`.
`int`	`STATE_DISCONNECTING` The state of a `Call` when the user has initiated a disconnection of the call, but the call has not yet been disconnected by the underlying `ConnectionService`.
`int`	`STATE_HOLDING` The state of a `Call` when in a holding state.
`int`	`STATE_NEW` The state of a `Call` when newly created.
`int`	`STATE_PULLING_CALL` The state of an external call which is in the process of being pulled from a remote device to the local device.
`int`	`STATE_RINGING` The state of an incoming `Call` when ringing locally, but not yet connected.
`int`	`STATE_SELECT_PHONE_ACCOUNT` The state of an outgoing `Call` when waiting on user to select a `PhoneAccount` through which to place the call.
`int`	`STATE_SIMULATED_RINGING` The state of a call that is being presented to the user after being in `STATE_AUDIO_PROCESSING`.

Public methods
`void`	`addConferenceParticipants(List<Uri> participants)` Pulls participants to existing call by forming a conference call.
`void`	`answer(int videoState)` Instructs this `STATE_RINGING` `Call` to answer.
`void`	`conference(Call callToConferenceWith)` Instructs this `Call` to enter a conference.
`void`	`deflect(Uri address)` Instructs this `STATE_RINGING` `Call` to deflect.
`void`	`disconnect()` Instructs this `Call` to disconnect.
`List<String>`	`getCannedTextResponses()` Obtains a list of canned, pre-configured message responses to present to the user as ways of rejecting an incoming `Call` using via a text message.
`List<Call>`	`getChildren()` Obtains the children of this conference `Call`, if any.
`List<Call>`	`getConferenceableCalls()` Returns the list of `Call`s with which this `Call` is allowed to conference.
`Call.Details`	`getDetails()` Obtains an object containing call details.
`Call`	`getGenericConferenceActiveChildCall()` Returns the child `Call` in a generic conference that is currently active.
`Call`	`getParent()` Obtains the parent of this `Call` in a conference, if any.
`String`	`getRemainingPostDialSequence()` Obtains the post-dial sequence remaining to be emitted by this `Call`, if any.
`Call.RttCall`	`getRttCall()` Returns this call's RttCall object.
`int`	`getState()` This method was deprecated in API level 31. The call state is available via `Call.Details#getState()`.
`InCallService.VideoCall`	`getVideoCall()` Obtains an object that can be used to display video from this `Call`.
`void`	`handoverTo(PhoneAccountHandle toHandle, int videoState, Bundle extras)` Initiates a handover of this `Call` to the `ConnectionService` identified by `toHandle`.
`void`	`hold()` Instructs this `Call` to go on hold.
`boolean`	`isRttActive()` Returns whether this call has an active RTT connection.
`void`	`mergeConference()` Merges the calls within this conference.
`void`	`phoneAccountSelected(PhoneAccountHandle accountHandle, boolean setDefault)` Notifies this `Call` that an account has been selected and to proceed with placing an outgoing call.
`void`	`playDtmfTone(char digit)` Instructs this `Call` to play a dual-tone multi-frequency signaling (DTMF) tone.
`void`	`postDialContinue(boolean proceed)` Instructs this `Call` to continue playing a post-dial DTMF string.
`void`	`pullExternalCall()` Initiates a request to the `ConnectionService` to pull an external call to the local device.
`void`	`putExtras(Bundle extras)` Adds some extras to this `Call`.
`void`	`registerCallback(Call.Callback callback)` Registers a callback to this `Call`.
`void`	`registerCallback(Call.Callback callback, Handler handler)` Registers a callback to this `Call`.
`void`	`reject(boolean rejectWithMessage, String textMessage)` Instructs this `STATE_RINGING` `Call` to reject.
`void`	`reject(int rejectReason)` Instructs the `ConnectionService` providing this `STATE_RINGING` call that the user has chosen to reject the call and has indicated a reason why the call is being rejected.
`void`	`removeExtras(List<String> keys)` Removes extras from this `Call`.
`void`	`removeExtras(String... keys)` Removes extras from this `Call`.
`void`	`respondToRttRequest(int id, boolean accept)` Responds to an RTT request received via the `Callback#onRttRequest(Call, int)` )} callback.
`void`	`sendCallEvent(String event, Bundle extras)` Sends a `Call` event from this `Call` to the associated `Connection` in the `ConnectionService`.
`void`	`sendRttRequest()` Sends an RTT upgrade request to the remote end of the connection.
`void`	`splitFromConference()` Instructs this `Call` to split from any conference call with which it may be connected.
`void`	`stopDtmfTone()` Instructs this `Call` to stop any dual-tone multi-frequency signaling (DTMF) tone currently playing.
`void`	`stopRtt()` Terminate the RTT session on this call.
`void`	`swapConference()` Swaps the calls within this conference.
`String`	`toString()` Returns a string representation of the object.
`void`	`unhold()` Instructs this `STATE_HOLDING` call to release from hold.
`void`	`unregisterCallback(Call.Callback callback)` Unregisters a callback from this `Call`.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

AVAILABLE_PHONE_ACCOUNTS

Added in API level 23
Deprecated in API level 29

public static final String AVAILABLE_PHONE_ACCOUNTS

This constant was deprecated in API level 29.
Use the list from EXTRA_SUGGESTED_PHONE_ACCOUNTS instead.

The key to retrieve the optional PhoneAccounts Telecom can bundle with its Call extras. Used to pass the phone accounts to display on the front end to the user in order to select phone accounts to (for example) place a call.

Constant Value: "selectPhoneAccountAccounts"

EVENT_CLEAR_DIAGNOSTIC_MESSAGE

Added in API level 31

public static final String EVENT_CLEAR_DIAGNOSTIC_MESSAGE

Event reported from the telecom framework when a diagnostic message previously raised with EVENT_DISPLAY_DIAGNOSTIC_MESSAGE has cleared and is no longer pertinent.

The EXTRA_DIAGNOSTIC_MESSAGE_ID indicates the diagnostic message which has been cleared.

The dialer app receives this event via Call.Callback#onConnectionEvent(Call, String, Bundle).

Constant Value: "android.telecom.event.CLEAR_DIAGNOSTIC_MESSAGE"

EVENT_DISPLAY_DIAGNOSTIC_MESSAGE

Added in API level 31

public static final String EVENT_DISPLAY_DIAGNOSTIC_MESSAGE

Event reported from the Telecom stack to report an in-call diagnostic message which the dialer app may opt to display to the user. A diagnostic message is used to communicate scenarios the device has detected which may impact the quality of the ongoing call.

For example a problem with a bluetooth headset may generate a recommendation for the user to try using the speakerphone instead, or if the device detects it has entered a poor service area, the user might be warned so that they can finish their call prior to it dropping.

A diagnostic message is considered persistent in nature. When the user enters a poor service area, for example, the accompanying diagnostic message persists until they leave the area of poor service. Each message is accompanied with a EXTRA_DIAGNOSTIC_MESSAGE_ID which uniquely identifies the diagnostic condition being reported. The framework raises a call event of type EVENT_CLEAR_DIAGNOSTIC_MESSAGE when the condition reported has been cleared. The dialer app should display the diagnostic message until it is cleared. If multiple diagnostic messages are sent with different IDs (which have not yet been cleared) the dialer app should prioritize the most recently received message, but still provide the user with a means to review past messages.

The text of the message is found in EXTRA_DIAGNOSTIC_MESSAGE in the form of a human readable CharSequence which is intended for display in the call UX.

The telecom framework audibly notifies the user of the presence of a diagnostic message, so the dialer app needs only to concern itself with visually displaying the message.

The dialer app receives this event via Call.Callback#onConnectionEvent(Call, String, Bundle).

Constant Value: "android.telecom.event.DISPLAY_DIAGNOSTIC_MESSAGE"

EXTRA_ASSERTED_DISPLAY_NAME

Added in API level 35

public static final String EXTRA_ASSERTED_DISPLAY_NAME

String value indicating the asserted display name reported via ImsCallProfile#EXTRA_ASSERTED_DISPLAY_NAME. Connection#setExtras(Bundle) or Connection#putExtras(Bundle) should be used to notify Telecom this extra has been set.

Constant Value: "android.telecom.extra.ASSERTED_DISPLAY_NAME"

EXTRA_DIAGNOSTIC_MESSAGE

Added in API level 31

public static final String EXTRA_DIAGNOSTIC_MESSAGE

CharSequence extra used with EVENT_DISPLAY_DIAGNOSTIC_MESSAGE. This is the diagnostic message the dialer app should display.

Constant Value: "android.telecom.extra.DIAGNOSTIC_MESSAGE"

EXTRA_DIAGNOSTIC_MESSAGE_ID

Added in API level 31

public static final String EXTRA_DIAGNOSTIC_MESSAGE_ID

Integer extra representing a message ID for a message posted via EVENT_DISPLAY_DIAGNOSTIC_MESSAGE. Used to ensure that the dialer app knows when the message in question has cleared via EVENT_CLEAR_DIAGNOSTIC_MESSAGE.

Constant Value: "android.telecom.extra.DIAGNOSTIC_MESSAGE_ID"

EXTRA_IS_BUSINESS_CALL

Added in API level 35

public static final String EXTRA_IS_BUSINESS_CALL

Boolean indicating that the call is a verified business call. Connection#setExtras(Bundle) or Connection#putExtras(Bundle) should be used to notify Telecom this extra has been set.

Constant Value: "android.telecom.extra.IS_BUSINESS_CALL"

EXTRA_IS_SUPPRESSED_BY_DO_NOT_DISTURB

Added in API level 34

public static final String EXTRA_IS_SUPPRESSED_BY_DO_NOT_DISTURB

Extra key intended for InCallServices that notify the user of an incoming call. When EXTRA_IS_SUPPRESSED_BY_DO_NOT_DISTURB returns true, the InCallService should not interrupt the user of the incoming call because the call is being suppressed by Do Not Disturb settings. This extra will be removed from the Call object for InCallServices that do not hold the Manifest.permission.READ_CONTACTS permission.

Constant Value: "android.telecom.extra.IS_SUPPRESSED_BY_DO_NOT_DISTURB"

EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

Added in API level 26

public static final String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC) when the last outgoing emergency call was made. This is used to identify potential emergency callbacks.

Constant Value: "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS"

EXTRA_SILENT_RINGING_REQUESTED

Added in API level 29

public static final String EXTRA_SILENT_RINGING_REQUESTED

Extra key used to indicate whether a CallScreeningService has requested to silence the ringtone for a call. If the InCallService declares TelecomManager#METADATA_IN_CALL_SERVICE_RINGING in its manifest, it should not play a ringtone for an incoming call with this extra key set.

Constant Value: "android.telecom.extra.SILENT_RINGING_REQUESTED"

EXTRA_SUGGESTED_PHONE_ACCOUNTS

Added in API level 29

public static final String EXTRA_SUGGESTED_PHONE_ACCOUNTS

Key for extra used to pass along a list of PhoneAccountSuggestions to the in-call UI when a call enters the STATE_SELECT_PHONE_ACCOUNT state. The list included here will have the same length and be in the same order as the list passed with AVAILABLE_PHONE_ACCOUNTS.

Constant Value: "android.telecom.extra.SUGGESTED_PHONE_ACCOUNTS"

REJECT_REASON_DECLINED

Added in API level 30

public static final int REJECT_REASON_DECLINED

Reject reason used with reject(int) to indicate that the user is rejecting this call because they have declined to answer it. This typically means that they are unable to answer the call at this time and would prefer it be sent to voicemail.

Constant Value: 1 (0x00000001)

REJECT_REASON_UNWANTED

Added in API level 30

public static final int REJECT_REASON_UNWANTED

Reject reason used with reject(int) to indicate that the user is rejecting this call because it is an unwanted call. This allows the user to indicate that they are rejecting a call because it is likely a nuisance call.

Constant Value: 2 (0x00000002)

STATE_ACTIVE

Added in API level 23

public static final int STATE_ACTIVE

The state of a Call when actively supporting conversation.

Constant Value: 4 (0x00000004)

STATE_AUDIO_PROCESSING

Added in API level 30

public static final int STATE_AUDIO_PROCESSING

The state of a call that is active with the network, but the audio from the call is being intercepted by an app on the local device. Telecom does not hold audio focus in this state, and the call will be invisible to the user except for a persistent notification.

Constant Value: 12 (0x0000000c)

STATE_CONNECTING

Added in API level 23

public static final int STATE_CONNECTING

The initial state of an outgoing Call. Common transitions are to STATE_DIALING state for a successful call or STATE_DISCONNECTED if it failed.

Constant Value: 9 (0x00000009)

STATE_DIALING

Added in API level 23

public static final int STATE_DIALING

The state of an outgoing Call when dialing the remote number, but not yet connected.

Constant Value: 1 (0x00000001)

STATE_DISCONNECTED

Added in API level 23

public static final int STATE_DISCONNECTED

The state of a Call when no further voice or other communication is being transmitted, the remote side has been or will inevitably be informed that the Call is no longer active, and the local data transport has or inevitably will release resources associated with this Call.

Constant Value: 7 (0x00000007)

STATE_DISCONNECTING

Added in API level 23

public static final int STATE_DISCONNECTING

The state of a Call when the user has initiated a disconnection of the call, but the call has not yet been disconnected by the underlying ConnectionService. The next state of the call is (potentially) STATE_DISCONNECTED.

Constant Value: 10 (0x0000000a)

STATE_HOLDING

Added in API level 23

public static final int STATE_HOLDING

The state of a Call when in a holding state.

Constant Value: 3 (0x00000003)

STATE_NEW

Added in API level 23

public static final int STATE_NEW

The state of a Call when newly created.

Constant Value: 0 (0x00000000)

STATE_PULLING_CALL

Added in API level 25

public static final int STATE_PULLING_CALL

The state of an external call which is in the process of being pulled from a remote device to the local device.

A call can only be in this state if the Details#PROPERTY_IS_EXTERNAL_CALL property and Details#CAPABILITY_CAN_PULL_CALL capability are set on the call.

An InCallService will only see this state if it has the TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS metadata set to true in its manifest.

Constant Value: 11 (0x0000000b)

STATE_RINGING

Added in API level 23

public static final int STATE_RINGING

The state of an incoming Call when ringing locally, but not yet connected.

Constant Value: 2 (0x00000002)

STATE_SELECT_PHONE_ACCOUNT

Added in API level 23

public static final int STATE_SELECT_PHONE_ACCOUNT

The state of an outgoing Call when waiting on user to select a PhoneAccount through which to place the call.

Constant Value: 8 (0x00000008)

STATE_SIMULATED_RINGING

Added in API level 30

public static final int STATE_SIMULATED_RINGING

The state of a call that is being presented to the user after being in STATE_AUDIO_PROCESSING. The call is still active with the network in this case, and Telecom will hold audio focus and play a ringtone if appropriate.

Constant Value: 13 (0x0000000d)

Public methods

addConferenceParticipants

Added in API level 31

public void addConferenceParticipants (List<Uri> participants)

Pulls participants to existing call by forming a conference call. See Details#CAPABILITY_ADD_PARTICIPANT.

Parameters
`participants`	`List`: participants to be pulled to existing call. This value cannot be `null`.

answer

Added in API level 23

public void answer (int videoState)

Instructs this STATE_RINGING Call to answer.

Parameters
`videoState`	`int`: The video state in which to answer the call. Value is either `0` or a combination of `VideoProfile.STATE_AUDIO_ONLY`, `VideoProfile.STATE_TX_ENABLED`, `VideoProfile.STATE_RX_ENABLED`, `VideoProfile.STATE_BIDIRECTIONAL`, and `VideoProfile.STATE_PAUSED`

conference

Added in API level 23

public void conference (Call callToConferenceWith)

Instructs this Call to enter a conference.

Parameters
`callToConferenceWith`	`Call`: The other call with which to conference.

deflect

Added in API level 28

public void deflect (Uri address)

Instructs this STATE_RINGING Call to deflect.

Parameters
`address`	`Uri`: The address to which the call will be deflected.

disconnect

Added in API level 23

public void disconnect ()

Instructs this Call to disconnect.

getCannedTextResponses

Added in API level 23

public List<String> getCannedTextResponses ()

Obtains a list of canned, pre-configured message responses to present to the user as ways of rejecting an incoming Call using via a text message.

Note: Since canned responses may be loaded from the file system, they are not guaranteed to be present when this Call is first added to the InCallService via InCallService#onCallAdded(Call). The callback Call.Callback#onCannedTextResponsesLoaded(Call, List) will be called when/if canned responses for the call become available.

Returns
`List<String>`	A list of canned text message responses.

See also:

reject(boolean, String)

getChildren

Added in API level 23

public List<Call> getChildren ()

Obtains the children of this conference Call, if any.

Returns
`List<Call>`	The children of this `Call` if this `Call` is a conference, or an empty `List` otherwise.

getConferenceableCalls

Added in API level 23

public List<Call> getConferenceableCalls ()

Returns the list of Calls with which this Call is allowed to conference.

Returns
`List<Call>`	The list of conferenceable `Call`s.

getDetails

Added in API level 23

public Call.Details getDetails ()

Obtains an object containing call details.

Returns
`Call.Details`	A `Details` object. Depending on the state of the `Call`, the result may be `null`.

getGenericConferenceActiveChildCall

Added in API level 30

public Call getGenericConferenceActiveChildCall ()

Returns the child Call in a generic conference that is currently active. A "generic conference" is the mechanism used to support two simultaneous calls on a device in CDMA networks. It is effectively equivalent to having one call active and one call on hold in GSM or IMS calls. This method returns the currently active call. In a generic conference, the network exposes the conference to us as a single call, and we switch between talking to the two participants using a CDMA flash command. Since the network exposes no additional information about the call, the only way we know which caller we're currently talking to is by keeping track of the flash commands that we've sent to the network. For calls that are not generic conferences, or when the generic conference has more than 2 children, returns null.

Returns
`Call`	The active child call.

See also:

Call.Details.PROPERTY_GENERIC_CONFERENCE

getParent

Added in API level 23

public Call getParent ()

Obtains the parent of this Call in a conference, if any.

Returns
`Call`	The parent `Call`, or `null` if this `Call` is not a child of any conference `Call`s.

getRemainingPostDialSequence

Added in API level 23

public String getRemainingPostDialSequence ()

Obtains the post-dial sequence remaining to be emitted by this Call, if any.

Returns
`String`	The remaining post-dial sequence, or `null` if there is no post-dial sequence remaining or this `Call` is not in a post-dial state.

getRttCall

Added in API level 26

public Call.RttCall getRttCall ()

Returns this call's RttCall object. The RttCall instance is used to send and receive RTT text data, as well as to change the RTT mode.

Returns
`Call.RttCall`	A `Call.RttCall`. `null` if there is no active RTT connection.

getState

Added in API level 23
Deprecated in API level 31

public int getState ()

This method was deprecated in API level 31.
The call state is available via Call.Details#getState().

Obtains the state of this Call.

Returns
`int`	The call state. Value is `STATE_NEW`, `STATE_DIALING`, `STATE_RINGING`, `STATE_HOLDING`, `STATE_ACTIVE`, `STATE_DISCONNECTED`, `STATE_SELECT_PHONE_ACCOUNT`, `STATE_CONNECTING`, `STATE_DISCONNECTING`, `STATE_PULLING_CALL`, `STATE_AUDIO_PROCESSING`, or `STATE_SIMULATED_RINGING`

getVideoCall

Added in API level 23

public InCallService.VideoCall getVideoCall ()

Obtains an object that can be used to display video from this Call.

Returns
`InCallService.VideoCall`	An `Call.VideoCall`.

handoverTo

Added in API level 28

public void handoverTo (PhoneAccountHandle toHandle, 
                int videoState, 
                Bundle extras)

Initiates a handover of this Call to the ConnectionService identified by toHandle. The videoState specified indicates the desired video state after the handover.

A call handover is the process where an ongoing call is transferred from one app (i.e. ConnectionService to another app. The user could, for example, choose to continue a mobile network call in a video calling app. The mobile network call via the Telephony stack is referred to as the source of the handover, and the video calling app is referred to as the destination.

When considering a handover scenario the device this method is called on is considered the initiating device (since the user initiates the handover from this device), and the other device is considered the receiving device.

When this method is called on the initiating device, the Telecom framework will bind to the ConnectionService defined by the toHandle PhoneAccountHandle and invoke ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle, ConnectionRequest) to inform the destination app that a request has been made to handover a call to it. The app returns an instance of Connection to represent the handover call At this point the app should display UI to indicate to the user that a call handover is in process.

The destination app is responsible for communicating the handover request from the initiating device to the receiving device.

When the app on the receiving device receives the handover request, it calls TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle) to continue the handover process from the initiating device to the receiving device. At this point the destination app on the receiving device should show UI to allow the user to choose whether they want to continue their call in the destination app.

When the destination app on the receiving device calls TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle), Telecom will bind to its ConnectionService and call ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle, ConnectionRequest) to inform it of the handover request. The app returns an instance of Connection to represent the handover call.

If the user of the receiving device accepts the handover, the app calls Connection#setActive() to complete the handover process; Telecom will disconnect the original call. If the user rejects the handover, the app calls Connection#setDisconnected(DisconnectCause) and specifies a DisconnectCause of DisconnectCause#CANCELED to indicate that the handover has been cancelled.

Telecom will only allow handovers from PhoneAccounts which declare PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM. Similarly, the PhoneAccount specified by toHandle must declare PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO.

Errors in the handover process are reported to the InCallService via Callback#onHandoverFailed(Call, int). Errors in the handover process are reported to the involved ConnectionServices via ConnectionService#onHandoverFailed(ConnectionRequest, int).

Parameters
`toHandle`	`PhoneAccountHandle`: `PhoneAccountHandle` of the `ConnectionService` to handover this call to.
`videoState`	`int`: Indicates the video state desired after the handover (see the `STATE_*` constants defined in `VideoProfile`). Value is either `0` or a combination of `VideoProfile.STATE_AUDIO_ONLY`, `VideoProfile.STATE_TX_ENABLED`, `VideoProfile.STATE_RX_ENABLED`, `VideoProfile.STATE_BIDIRECTIONAL`, and `VideoProfile.STATE_PAUSED`
`extras`	`Bundle`: Bundle containing extra information to be passed to the `ConnectionService`

hold

Added in API level 23

public void hold ()

Instructs this Call to go on hold.

isRttActive

Added in API level 26

public boolean isRttActive ()

Returns whether this call has an active RTT connection.

Returns
`boolean`	true if there is a connection, false otherwise.

mergeConference

Added in API level 23

public void mergeConference ()

Merges the calls within this conference. See Details#CAPABILITY_MERGE_CONFERENCE.

phoneAccountSelected

Added in API level 23

public void phoneAccountSelected (PhoneAccountHandle accountHandle, 
                boolean setDefault)

Notifies this Call that an account has been selected and to proceed with placing an outgoing call. Optionally sets this account as the default account.

Parameters
`accountHandle`	`PhoneAccountHandle`
`setDefault`	`boolean`

playDtmfTone

Added in API level 23

public void playDtmfTone (char digit)

Instructs this Call to play a dual-tone multi-frequency signaling (DTMF) tone.

Tones are both played locally for the user to hear and sent to the network to be relayed to the remote device.

You must ensure that any call to playDtmfTone(char) is followed by a matching call to stopDtmfTone() and that each tone is stopped before a new one is started. The play and stop commands are relayed to the underlying ConnectionService as executed; implementations may not correctly handle out of order commands.

Parameters
`digit`	`char`: A character representing the DTMF digit for which to play the tone. This value must be one of `'0'` through `'9'`, `'*'` or `'#'`.

postDialContinue

Added in API level 23

public void postDialContinue (boolean proceed)

Instructs this Call to continue playing a post-dial DTMF string. A post-dial DTMF string is a string of digits entered after a phone number, when dialed, that are immediately sent as DTMF tones to the recipient as soon as the connection is made. If the DTMF string contains a TelecomManager#DTMF_CHARACTER_PAUSE symbol, this Call will temporarily pause playing the tones for a pre-defined period of time. If the DTMF string contains a TelecomManager#DTMF_CHARACTER_WAIT symbol, this Call will pause playing the tones and notify callbacks via Callback#onPostDialWait(Call, String). At this point, the in-call app should display to the user an indication of this state and an affordance to continue the postdial sequence. When the user decides to continue the postdial sequence, the in-call app should invoke the postDialContinue(boolean) method.

Parameters
`proceed`	`boolean`: Whether or not to continue with the post-dial sequence.

pullExternalCall

Added in API level 25

public void pullExternalCall ()

Initiates a request to the ConnectionService to pull an external call to the local device.

Calls to this method are ignored if the call does not have the Call.Details#PROPERTY_IS_EXTERNAL_CALL property set.

An InCallService will only see calls which support this method if it has the TelecomManager#METADATA_INCLUDE_EXTERNAL_CALLS metadata set to true in its manifest.

putExtras

Added in API level 25

public void putExtras (Bundle extras)

Adds some extras to this Call. Existing keys are replaced and new ones are added.

No assumptions should be made as to how an In-Call UI or service will handle these extras. Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.

Extras added using this method will be made available to the ConnectionService associated with this Call and notified via Connection#onExtrasChanged(Bundle).

Extras added using this method will also be available to other running InCallServices and notified via Call.Callback#onDetailsChanged(Call, Details). The extras can be accessed via Details#getExtras().

Parameters
`extras`	`Bundle`: The extras to add.

registerCallback

Added in API level 23

public void registerCallback (Call.Callback callback)

Registers a callback to this Call.

Parameters
`callback`	`Call.Callback`: A `Callback`.

registerCallback

Added in API level 23

public void registerCallback (Call.Callback callback, 
                Handler handler)

Registers a callback to this Call.

Parameters
`callback`	`Call.Callback`: A `Callback`.
`handler`	`Handler`: A handler which command and status changes will be delivered to.

reject

Added in API level 23

public void reject (boolean rejectWithMessage, 
                String textMessage)

Instructs this STATE_RINGING Call to reject.

Parameters
`rejectWithMessage`	`boolean`: Whether to reject with a text message.
`textMessage`	`String`: An optional text message with which to respond.

reject

Added in API level 30

public void reject (int rejectReason)

Instructs the ConnectionService providing this STATE_RINGING call that the user has chosen to reject the call and has indicated a reason why the call is being rejected.

Parameters
`rejectReason`	`int`: the reason the call is being rejected. Value is `REJECT_REASON_DECLINED`, or `REJECT_REASON_UNWANTED`

removeExtras

Added in API level 25

public void removeExtras (List<String> keys)

Removes extras from this Call.

Parameters
`keys`	`List`: The keys of the extras to remove.

removeExtras

Added in API level 25

public void removeExtras (String... keys)

Removes extras from this Call.

Parameters
`keys`	`String`: The keys of the extras to remove.

respondToRttRequest

Added in API level 26

public void respondToRttRequest (int id, 
                boolean accept)

Responds to an RTT request received via the Callback#onRttRequest(Call, int) )} callback. The ID used here should be the same as the ID that was received via the callback.

Parameters
`id`	`int`: The request ID received via `Callback#onRttRequest(Call, int)`
`accept`	`boolean`: `true` if the RTT request should be accepted, `false` otherwise.

sendCallEvent

Added in API level 25

public void sendCallEvent (String event, 
                Bundle extras)

Sends a Call event from this Call to the associated Connection in the ConnectionService.

Call events are used to communicate point in time information from an InCallService to a ConnectionService. A ConnectionService implementation could define events which enable the InCallService, for example, toggle a unique feature of the ConnectionService.

A ConnectionService can communicate to the InCallService using Connection#sendConnectionEvent(String, Bundle).

Events are exposed to ConnectionService implementations via Connection.onCallEvent(String, Bundle).

No assumptions should be made as to how a ConnectionService will handle these events. The InCallService must assume that the ConnectionService could chose to ignore some events altogether.

Events should be fully qualified (e.g., com.example.event.MY_EVENT) to avoid conflicts between InCallService implementations. Further, InCallService implementations shall not re-purpose events in the android.* namespace, nor shall they define their own event types in this namespace. When defining a custom event type, ensure the contents of the extras Bundle is clearly defined. Extra keys for this bundle should be named similar to the event type (e.g. com.example.extra.MY_EXTRA).

When defining events and the associated extras, it is important to keep their behavior consistent when the associated InCallService is updated. Support for deprecated events/extras should me maintained to ensure backwards compatibility with older ConnectionService implementations which were built to support the older behavior.

Parameters
`event`	`String`: The connection event.
`extras`	`Bundle`: Bundle containing extra information associated with the event.

sendRttRequest

Added in API level 26

public void sendRttRequest ()

Sends an RTT upgrade request to the remote end of the connection. Success is not guaranteed, and notification of success will be via the Callback#onRttStatusChanged(Call, boolean, RttCall) callback.

splitFromConference

Added in API level 23

public void splitFromConference ()

Instructs this Call to split from any conference call with which it may be connected.

stopDtmfTone

Added in API level 23

public void stopDtmfTone ()

Instructs this Call to stop any dual-tone multi-frequency signaling (DTMF) tone currently playing. DTMF tones are played by calling playDtmfTone(char). If no DTMF tone is currently playing, this method will do nothing.

stopRtt

Added in API level 26

public void stopRtt ()

Terminate the RTT session on this call. The resulting state change will be notified via the Callback#onRttStatusChanged(Call, boolean, RttCall) callback.

swapConference

Added in API level 23

public void swapConference ()

Swaps the calls within this conference. See Details#CAPABILITY_SWAP_CONFERENCE.

toString

Added in API level 23

public String toString ()

Returns a string representation of the object.

Returns
`String`	a string representation of the object.

unhold

Added in API level 23

public void unhold ()

Instructs this STATE_HOLDING call to release from hold.

unregisterCallback

Added in API level 23

public void unregisterCallback (Call.Callback callback)

Unregisters a callback from this Call.

Parameters
`callback`	`Call.Callback`: A `Callback`.

Call

Summary

Nested classes

Constants

Public methods

Inherited methods

Constants

AVAILABLE_PHONE_ACCOUNTS

EVENT_CLEAR_DIAGNOSTIC_MESSAGE

EVENT_DISPLAY_DIAGNOSTIC_MESSAGE

EXTRA_ASSERTED_DISPLAY_NAME

EXTRA_DIAGNOSTIC_MESSAGE

EXTRA_DIAGNOSTIC_MESSAGE_ID

EXTRA_IS_BUSINESS_CALL

EXTRA_IS_SUPPRESSED_BY_DO_NOT_DISTURB

EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

EXTRA_SILENT_RINGING_REQUESTED

EXTRA_SUGGESTED_PHONE_ACCOUNTS

REJECT_REASON_DECLINED

REJECT_REASON_UNWANTED

STATE_ACTIVE

STATE_AUDIO_PROCESSING

STATE_CONNECTING

STATE_DIALING

STATE_DISCONNECTED

STATE_DISCONNECTING

STATE_HOLDING

STATE_NEW

STATE_PULLING_CALL

STATE_RINGING

STATE_SELECT_PHONE_ACCOUNT

STATE_SIMULATED_RINGING

Public methods

addConferenceParticipants

answer

conference

deflect

disconnect

getCannedTextResponses

getChildren

getConferenceableCalls

getDetails

getGenericConferenceActiveChildCall

getParent

getRemainingPostDialSequence

getRttCall

getState

getVideoCall

handoverTo

hold

isRttActive

mergeConference

phoneAccountSelected

playDtmfTone

postDialContinue

pullExternalCall

putExtras

registerCallback

registerCallback

reject

reject

removeExtras

removeExtras

respondToRttRequest

sendCallEvent

sendRttRequest

splitFromConference

stopDtmfTone

stopRtt

swapConference

toString

unhold

unregisterCallback