Google is committed to advancing racial equity for Black communities. See how.

Telecom framework overview

The Android Telecom framework manages audio and video calls on an Android device. This includes SIM-based calls (e.g. using the Telephony framework) as well as VOIP calls provided by implementors of the ConnectionService API.

The two major components which Telecom deals with are ConnectionServices and InCallServices. A ConnectionService implementation is responsible for connecting calls to another party using some means (e.g. VOIP). The most common ConnectionService implementation on a phone is the Telephony ConnectionService which is responsible for connecting carrier calls. A InCallService implementation is responsible for providing a user interface to calls managed by Telecom and for providing the user with a means to control and interact with these calls. The Phone app bundled with a device is the most common example of an implementation of an InCallService .

Telecom acts as a switchboard, routing calls which are provided by ConnectionService implementations to the calling user interface provided by InCallService implementations.

You might want to implement the Telecom APIs if:

  1. You want to create a replacement for the system Phone app.
  2. You want to create a calling solution which integrates into the Android calling experience.

Create a replacement phone app

If you want to create a replacement for the default Phone app on an Android device, implement the InCallService API. It is important to note that an InCallService should not have any calling capability and consists solely of the user-interface for calling. An InCallService must handle all Calls the Telecom framework is aware of. It must not make assumptions about the nature of the calls (e.g. assuming calls are SIM-based telephony calls), and should not implement calling restrictions based on any one ConnectionService (e.g. it should not enforce Telephony restrictions for video calls).

For more information, see InCallService.

Integrate a calling solution

If you want to integrate your calling solution into Android, you have the following options:

  1. Implement the self-managed ConnectionService API - this is ideal for developers of standalone calling apps which do not wish to show their calls within the default phone app, and do not wish to have other calls shown in their user interface. Traditionally, standalone calling apps have relied on listening to the phone state to try to determine when other calls are taking place. This is problematic as the phone state does not take into account other calling apps the user may have installed. Using a self-managed ConnectionService helps you ensure that your app will interoperate not only with native telephony calling on the device, but also other standalone calling apps implementing this API. The Self-Managed ConnectionService API also manages audio routing and focus for you. For details, see Self-Managed ConnectionServices
  2. Implement the managed ConnectionService API - facilitates development of a calling solution that relies on the existing device phone application (see getDefaultDialerPackage()) to provide the user interface for calls. An example might be a third party implementation of SIP calling, or a VOIP calling service. A ConnectionService alone provides only the means of connecting calls, but has no associated user interface. For details, see ConnectionService.
  3. Implement both the InCallService and ConnectionService API - ideal if you wish to create your own ConnectionService based calling solution, complete with its own user interface, while also showing all other Android calls in the same user interface. Using this approach, you must still ensure that your InCallService makes no assumption about the source of the calls it displays. You must also ensure that your ConnectionService implementation can still function without the default phone app being set to your custom InCallService.

Screen calls

Devices running Android 10 (API level 29) and higher provide your app with a means to identify calls not in the user's address book as potential spam calls, and to have spam calls silently rejected on behalf of the user. Information about these blocked calls is logged as blocked calls in the call log to provide greater transparency to the user when they are missing calls. Use of this new API eliminates the requirement to obtain READ_CALL_LOG permissions from the user to provide call screening and caller ID functionality.

Redirect a call

On devices running Android 10 (API level 29) and higher, call intents are handled differently than on devices running Android 9 and lower. The NEW_OUTGOING_CALL broadcast is deprecated and is replaced with the CallRedirectionService API. The CallRedirectionService API provides interfaces for you to modify outgoing calls made by the Android platform. For example, third-party apps might cancel calls and reroute them over VoIP.