Added in API level 24

CallScreeningService


abstract class CallScreeningService : Service
kotlin.Any
   ↳ 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. A can also see outgoing calls for the purpose of providing caller ID services for those calls.

Below is an example manifest registration for a CallScreeningService.

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

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 - services which provide call identification functionality can display a user-interface of their choosing which contains identifying information for a call.

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(RoleManager.ROLE_CALL_SCREENING);
      startActivityForResult(intent, REQUEST_ID);
  }
 
  &amp;#64;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
          }
      }
  }
  </code>

CallScreeningService Lifecycle

The framework binds to the CallScreeningService implemented by the user-chosen app filling the android.app.role.RoleManager#ROLE_CALL_SCREENING role when incoming calls are received (prior to ringing) and when outgoing calls are placed. The platform calls the onScreenCall(android.telecom.Call.Details) method to provide your service with details about the call.

For incoming calls, the CallScreeningService must call respondToCall(android.telecom.Call.Details,android.telecom.CallScreeningService.CallResponse) within 5 seconds of being bound to indicate to the platform whether the call should be blocked or not. Your app must do this even if it is primarily performing caller ID operations and not screening calls. It is important to perform screening operations in a timely matter as the user's device will not begin ringing until the response is received (or the timeout is hit). A CallScreeningService may choose to perform local database lookups to help determine if a call should be screened or not; care should be taken to ensure the timeout is not repeatedly hit, causing delays in the incoming call flow.

If your app provides a caller ID experience, it should launch an activity to show the caller ID information from onScreenCall(android.telecom.Call.Details).

Summary

Nested classes
open

Information about how to respond to an incoming call.

Constants
static String

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

Inherited constants
Public constructors

Public methods
open IBinder?
onBind(intent: Intent!)

abstract Unit
onScreenCall(callDetails: Call.Details)

Called when a new incoming or outgoing call is added.

open Boolean
onUnbind(intent: Intent!)

Unit

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

Inherited functions

Constants

SERVICE_INTERFACE

Added in API level 24
static val SERVICE_INTERFACE: String

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

Value: "android.telecom.CallScreeningService"

Public constructors

CallScreeningService

Added in API level 24
CallScreeningService()

Public methods

onBind

Added in API level 24
open fun onBind(intent: Intent!): IBinder?
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

onScreenCall

Added in API level 24
abstract fun onScreenCall(callDetails: Call.Details): Unit

Called when a new incoming or outgoing call is added.

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.

Note: A CallScreeningService must respond to a call within 5 seconds. After this time, the framework will unbind from the CallScreeningService and ignore its response.

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 handle scheme is PhoneAccount#SCHEME_TEL are passed for call screening. Further, only calls which are not in the user's contacts are passed for screening, unless the CallScreeningService has been granted Manifest.permission#READ_CONTACTS permission by the user. For outgoing calls, no post-dial digits are passed.

Calls with a Call.Details#getHandlePresentation() of TelecomManager#PRESENTATION_RESTRICTED, TelecomManager#PRESENTATION_UNKNOWN, TelecomManager#PRESENTATION_UNAVAILABLE or TelecomManager#PRESENTATION_PAYPHONE presentation are not provided to the CallScreeningService.

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

onUnbind

Added in API level 24
open fun onUnbind(intent: Intent!): Boolean
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
Boolean Return true if you would like to have the service's onRebind method later called when new clients bind to it.

respondToCall

Added in API level 24
fun respondToCall(
    callDetails: Call.Details,
    response: CallScreeningService.CallResponse
): Unit

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

The CallScreeningService calls this method to inform the system whether the call should be silently blocked or not. In the event that it should not be blocked, it may also be requested to ring silently.

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

For incoming calls, a CallScreeningService MUST call this method within 5 seconds of onScreenCall(android.telecom.Call.Details) being invoked by the platform.

Calls which are blocked/rejected will be logged to the system call log with a call type of android.provider.CallLog.Calls#BLOCKED_TYPE and android.provider.CallLog.Calls#BLOCK_REASON_CALL_SCREENING_SERVICE block reason.

Parameters
callDetails Call.Details: The call to allow.

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

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