Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

CallScreeningService

public abstract class CallScreeningService
extends Service

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


This service can be implemented by the default dialer (see TelecomManager#getDefaultDialerPackage()) or a third party app to allow or disallow incoming calls before they are shown to a user. This service can also provide CallIdentification information for calls.

Below is an example manifest registration for a CallScreeningService.

 <service android:name="your.package.YourCallScreeningServiceImplementation"
          android:permission="android.permission.BIND_SCREENING_SERVICE">
      <intent-filter>
          <action android:name="android.telecom.CallScreeningService"/>
      </intent-filter>
 </service>
 
 

A CallScreeningService performs two functions:

  1. Call blocking/screening - the service can choose which calls will ring on the user's device, and which will be silently sent to voicemail.
  2. Call identification - the service can optionally provide CallIdentification information about a Call.Details which will be shown to the user in the Dialer app.

Becoming the CallScreeningService

Telecom will bind to a single app chosen by the user which implements the CallScreeningService API when there are new incoming and outgoing calls.

The code snippet below illustrates how your app can request that it fills the call screening role.

 {@code
 private static final int REQUEST_ID = 1;

 public void requestRole() {
     RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
     Intent intent = roleManager.createRequestRoleIntent("android.app.role.CALL_SCREENING");
     startActivityForResult(intent, REQUEST_ID);
 }

 @Override
 public void onActivityResult(int requestCode, int resultCode, Intent data) {
     if (requestCode == REQUEST_ID) {
         if (resultCode == android.app.Activity.RESULT_OK) {
             // Your app is now the call screening app
         } else {
             // Your app is not the call screening app
         }
     }
 }
 

Summary

Nested classes

class CallScreeningService.CallResponse

 

Constants

String ACTION_NUISANCE_CALL_STATUS_CHANGED

Telecom sends this intent to the CallScreeningService which the user has chosen to fill the call screening role when the user indicates through the default dialer whether a call is a nuisance call or not (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

int CALL_DURATION_LONG

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

int CALL_DURATION_MEDIUM

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

int CALL_DURATION_SHORT

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

int CALL_DURATION_VERY_SHORT

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

String EXTRA_CALL_DURATION

Integer extra used to with ACTION_NUISANCE_CALL_STATUS_CHANGED to report how long the call lasted.

String EXTRA_CALL_HANDLE

Extra used to provide the handle of the call for ACTION_NUISANCE_CALL_STATUS_CHANGED.

String EXTRA_CALL_TYPE

Integer extra used with ACTION_NUISANCE_CALL_STATUS_CHANGED to report the type of call.

String EXTRA_IS_NUISANCE

Boolean extra used to indicate whether the user reported a call as a nuisance call.

String SERVICE_INTERFACE

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

Inherited constants

Public constructors

CallScreeningService()

Public methods

IBinder onBind(Intent intent)

Return the communication channel to the service.

abstract void onScreenCall(Call.Details callDetails)

Called when a new incoming or outgoing call is added which is not in the user's contact list.

boolean onUnbind(Intent intent)

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

final void provideCallIdentification(Call.Details callDetails, CallIdentification identification)

Provide CallIdentification information about a Call.Details.

final void respondToCall(Call.Details callDetails, CallScreeningService.CallResponse response)

Responds to the given incoming call, either allowing it or disallowing it.

Inherited methods

Constants

ACTION_NUISANCE_CALL_STATUS_CHANGED

public static final String ACTION_NUISANCE_CALL_STATUS_CHANGED

Telecom sends this intent to the CallScreeningService which the user has chosen to fill the call screening role when the user indicates through the default dialer whether a call is a nuisance call or not (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)).

The following extra values are provided for the call:

  1. EXTRA_CALL_HANDLE - the handle of the call.
  2. EXTRA_IS_NUISANCE - true if the user reported the call as a nuisance call, false otherwise.
  3. EXTRA_CALL_TYPE - reports the type of call (incoming, rejected, missed, blocked).
  4. EXTRA_CALL_DURATION - the duration of the call (see EXTRA_CALL_DURATION for valid values).

CallScreeningService implementations which want to track whether the user reports calls are nuisance calls should use declare a broadcast receiver in their manifest for this intent.

Note: Only CallScreeningService implementations which have provided CallIdentification information for calls at some point will receive this intent.

Constant Value: "android.telecom.action.NUISANCE_CALL_STATUS_CHANGED"

CALL_DURATION_LONG

public static final int CALL_DURATION_LONG

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)). The CallScreeningService can use this as a signal for training nuisance detection algorithms. The call duration is reported in coarse grained buckets to minimize exposure of identifying call log information to the CallScreeningService.

Indicates the call was greater than 120 seconds.

Constant Value: 4 (0x00000004)

CALL_DURATION_MEDIUM

public static final int CALL_DURATION_MEDIUM

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)). The CallScreeningService can use this as a signal for training nuisance detection algorithms. The call duration is reported in coarse grained buckets to minimize exposure of identifying call log information to the CallScreeningService.

Indicates the call was greater than 60 seconds, but less than 120 seconds in duration.

Constant Value: 3 (0x00000003)

CALL_DURATION_SHORT

public static final int CALL_DURATION_SHORT

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)). The CallScreeningService can use this as a signal for training nuisance detection algorithms. The call duration is reported in coarse grained buckets to minimize exposure of identifying call log information to the CallScreeningService.

Indicates the call was greater than 3 seconds, but less than 60 seconds in duration.

Constant Value: 2 (0x00000002)

CALL_DURATION_VERY_SHORT

public static final int CALL_DURATION_VERY_SHORT

Call duration reported with EXTRA_CALL_DURATION to indicate to the CallScreeningService the duration of a call for which the user reported the nuisance status (see TelecomManager#reportNuisanceCallStatus(Uri, boolean)). The CallScreeningService can use this as a signal for training nuisance detection algorithms. The call duration is reported in coarse grained buckets to minimize exposure of identifying call log information to the CallScreeningService.

Indicates the call was < 3 seconds in duration.

Constant Value: 1 (0x00000001)

EXTRA_CALL_DURATION

public static final String EXTRA_CALL_DURATION

Integer extra used to with ACTION_NUISANCE_CALL_STATUS_CHANGED to report how long the call lasted. Valid values are:

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

EXTRA_CALL_HANDLE

public static final String EXTRA_CALL_HANDLE

Extra used to provide the handle of the call for ACTION_NUISANCE_CALL_STATUS_CHANGED. The call handle is reported as a Uri.

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

EXTRA_CALL_TYPE

public static final String EXTRA_CALL_TYPE

Integer extra used with ACTION_NUISANCE_CALL_STATUS_CHANGED to report the type of call. Valid values are:

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

EXTRA_IS_NUISANCE

public static final String EXTRA_IS_NUISANCE

Boolean extra used to indicate whether the user reported a call as a nuisance call. When true, the user reported that a call was a nuisance call, false otherwise. Sent with ACTION_NUISANCE_CALL_STATUS_CHANGED.

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

SERVICE_INTERFACE

Added in API level 24
public static final String SERVICE_INTERFACE

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

Constant Value: "android.telecom.CallScreeningService"

Public constructors

CallScreeningService

Added in API level 24
public CallScreeningService ()

Public methods

onBind

Added in API level 24
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.

onScreenCall

Added in API level 24
public abstract void onScreenCall (Call.Details callDetails)

Called when a new incoming or outgoing call is added which is not in the user's contact list.

A CallScreeningService must indicate whether an incoming call is allowed or not by calling CallScreeningService#respondToCall(Call.Details, CallScreeningService.CallResponse). Your app can tell if a call is an incoming call by checking to see if Call.Details#getCallDirection() is Call.Details#DIRECTION_INCOMING.

For incoming or outgoing calls, the CallScreeningService can call provideCallIdentification(android.telecom.Call.Details, android.telecom.CallIdentification) in order to provide CallIdentification for the call.

Note: The Call.Details instance provided to a call screening service will only have the following properties set. The rest of the Call.Details properties will be set to their default value or null.

Only calls where the Call.Details#getHandle() Uri#getScheme() is PhoneAccount#SCHEME_TEL are passed for call screening. Further, only calls which are not in the user's contacts are passed for screening. For outgoing calls, no post-dial digits are passed.

Parameters
callDetails Call.Details: Information about a new call, see Call.Details. This value must never be null.

onUnbind

Added in API level 24
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.

provideCallIdentification

public final void provideCallIdentification (Call.Details callDetails, 
                CallIdentification identification)

Provide CallIdentification information about a Call.Details.

The CallScreeningService calls this method to provide information it has identified about a Call.Details. This information will potentially be shown to the user in the InCallService app. It will be logged to the CallLog.

A CallScreeningService should only call this method for calls for which it is able to provide some CallIdentification for. CallIdentification instances with no fields set will be ignored by the system.

Parameters
callDetails Call.Details: The call to provide information for.

Must be the same Call.Details which was provided to the CallScreeningService via onScreenCall(android.telecom.Call.Details). This value must never be null.

identification CallIdentification: An instance of CallIdentification with information about the Call.Details. This value must never be null.

respondToCall

Added in API level 24
public final void respondToCall (Call.Details callDetails, 
                CallScreeningService.CallResponse response)

Responds to the given incoming call, either allowing it or disallowing it.

The CallScreeningService calls this method to inform the system whether the call should be silently blocked or not.

Calls to this method are ignored unless the Call.Details#getCallDirection() is Call.Details#DIRECTION_INCOMING.

Parameters
callDetails Call.Details: The call to allow.

Must be the same Call.Details which was provided to the CallScreeningService via onScreenCall(android.telecom.Call.Details). This value must never be null.

response CallScreeningService.CallResponse: The CallScreeningService.CallResponse which contains information about how to respond to a call. This value must never be null.