lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

InCallService

public abstract class InCallService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.telecom.InCallService


This service is implemented by any app that wishes to provide the user-interface for managing phone calls. Telecom binds to this service while there exists a live (active or incoming) call, and uses it to notify the in-call app of any live and recently disconnected calls. An app must first be set as the default phone app (See TelecomManager.getDefaultDialerPackage()) before the telecom service will bind to its InCallService implementation.

Below is an example manifest registration for an InCallService. The meta-data (TelecomManager.METADATA_IN_CALL_SERVICE_UI) indicates that this particular InCallService implementation intends to replace the built-in in-call UI.

 <service android:name="your.package.YourInCallServiceImplementation"
          android:permission="android.permission.BIND_INCALL_SERVICE">
      <meta-data android:name="android.telecom.IN_CALL_SERVICE_UI" android:value="true" />
      <intent-filter>
          <action android:name="android.telecom.InCallService"/>
      </intent-filter>
 </service>
 
 

In addition to implementing the InCallService API, you must also declare an activity in your manifest which handles the Intent.ACTION_DIAL intent. The example below illustrates how this is done:

 <activity android:name="your.package.YourDialerActivity"
           android:label="@string/yourDialerActivityLabel">
      <intent-filter>
           <action android:name="android.intent.action.DIAL" />
           <category android:name="android.intent.category.DEFAULT" />
      </intent-filter>
 </activity>
 
 

When a user installs your application and runs it for the first time, you should prompt the user to see if they would like your application to be the new default phone app. See the TelecomManager.ACTION_CHANGE_DEFAULT_DIALER intent documentation for more information on how to do this.

Summary

Nested classes

class InCallService.VideoCall

Used to issue commands to the Connection.VideoProvider associated with a Call

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Inherited constants

Public constructors

InCallService()

Public methods

final boolean canAddCall()

Returns if the device can support additional calls.

final CallAudioState getCallAudioState()

Obtains the current phone call audio state.

final List<Call> getCalls()

Obtains the current list of Calls to be displayed by this in-call service.

IBinder onBind(Intent intent)

Return the communication channel to the service.

void onBringToForeground(boolean showDialpad)

Called to bring the in-call screen to the foreground.

void onCallAdded(Call call)

Called when a Call has been added to this in-call session.

void onCallAudioStateChanged(CallAudioState audioState)

Called when the audio state changes.

void onCallRemoved(Call call)

Called when a Call has been removed from this in-call session.

void onCanAddCallChanged(boolean canAddCall)

Called when the ability to add more calls changes.

void onConnectionEvent(Call call, String event, Bundle extras)

Unused; to handle connection events issued by a ConnectionService, implement the Call.Callback.onConnectionEvent(Call, String, Bundle) callback.

void onSilenceRinger()

Called to silence the ringer if a ringing call exists.

boolean onUnbind(Intent intent)

Called when all clients have disconnected from a particular interface published by the service.

final void requestBluetoothAudio(BluetoothDevice bluetoothDevice)

Request audio routing to a specific bluetooth device.

final void setAudioRoute(int route)

Sets the audio route (speaker, bluetooth, etc...).

final void setMuted(boolean state)

Sets the microphone mute state.

Inherited methods

Constants

SERVICE_INTERFACE

added in API level 23
public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.telecom.InCallService"

Public constructors

InCallService

added in API level 23
public InCallService ()

Public methods

canAddCall

added in API level 23
public final boolean canAddCall ()

Returns if the device can support additional calls.

Returns
boolean Whether the phone supports adding more calls.

getCallAudioState

added in API level 23
public final CallAudioState getCallAudioState ()

Obtains the current phone call audio state.

Returns
CallAudioState An object encapsulating the audio state. Returns null if the service is not fully initialized.

getCalls

added in API level 23
public final List<Call> getCalls ()

Obtains the current list of Calls to be displayed by this in-call service.

Returns
List<Call> A list of the relevant Calls.

onBind

added in API level 23
public IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
IBinder Return an IBinder through which clients can call on to the service.

onBringToForeground

added in API level 23
public void onBringToForeground (boolean showDialpad)

Called to bring the in-call screen to the foreground. The in-call experience should respond immediately by coming to the foreground to inform the user of the state of ongoing Calls.

Parameters
showDialpad boolean: If true, put up the dialpad when the screen is shown.

onCallAdded

added in API level 23
public void onCallAdded (Call call)

Called when a Call has been added to this in-call session. The in-call user experience should add necessary state listeners to the specified Call and immediately start to show the user information about the existence and nature of this Call. Subsequent invocations of getCalls() will include this Call.

Parameters
call Call: A newly added Call.

onCallAudioStateChanged

added in API level 23
public void onCallAudioStateChanged (CallAudioState audioState)

Called when the audio state changes.

Parameters
audioState CallAudioState: The new CallAudioState.

onCallRemoved

added in API level 23
public void onCallRemoved (Call call)

Called when a Call has been removed from this in-call session. The in-call user experience should remove any state listeners from the specified Call and immediately stop displaying any information about this Call. Subsequent invocations of getCalls() will no longer include this Call.

Parameters
call Call: A newly removed Call.

onCanAddCallChanged

added in API level 23
public void onCanAddCallChanged (boolean canAddCall)

Called when the ability to add more calls changes. If the phone cannot support more calls then canAddCall is set to false. If it can, then it is set to true. This can be used to control the visibility of UI to add more calls.

Parameters
canAddCall boolean: Indicates whether an additional call can be added.

onConnectionEvent

added in API level 25
public void onConnectionEvent (Call call, 
                String event, 
                Bundle extras)

Unused; to handle connection events issued by a ConnectionService, implement the Call.Callback.onConnectionEvent(Call, String, Bundle) callback.

See Connection.sendConnectionEvent(String, Bundle).

Parameters
call Call: The call the event is associated with.

event String: The event.

extras Bundle: Any associated extras.

onSilenceRinger

added in API level 24
public void onSilenceRinger ()

Called to silence the ringer if a ringing call exists.

onUnbind

added in API level 23
public boolean onUnbind (Intent intent)

Called when all clients have disconnected from a particular interface published by the service. The default implementation does nothing and returns false.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
boolean Return true if you would like to have the service's onRebind(Intent) method later called when new clients bind to it.

requestBluetoothAudio

added in API level 28
public final void requestBluetoothAudio (BluetoothDevice bluetoothDevice)

Request audio routing to a specific bluetooth device. Calling this method may result in the device routing audio to a different bluetooth device than the one specified if the bluetooth stack is unable to route audio to the requested device. A list of available devices can be obtained via CallAudioState.getSupportedBluetoothDevices()

Parameters
bluetoothDevice BluetoothDevice: The bluetooth device to connect to.

This value must never be null.

setAudioRoute

added in API level 23
public final void setAudioRoute (int route)

Sets the audio route (speaker, bluetooth, etc...). When this request is honored, there will be change to the getCallAudioState().

Parameters
route int: The audio route to use.

setMuted

added in API level 23
public final void setMuted (boolean state)

Sets the microphone mute state. When this request is honored, there will be change to the getCallAudioState().

Parameters
state boolean: true if the microphone should be muted; false otherwise.