Added in API level 21

android.telecom

The Android Telecom framework is responsible for managing calls on an Android device. This can include SIM-based calls using the Telephony framework, VOIP calls using SIP (e.g. the SipConnectionService), or via a third-party VOIP ConnectionService. Telecom acts as a switchboard, routing calls and audio focus between Connections provided by ConnectionService implementations, and InCallService implementations which provide a user interface for calls.

Android supports the following calling use cases (with increasing level of complexity):

  • 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. Using a self-managed ConnectionService implementation within your standalone calling app 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. It also manages audio routing and focus for you.
  • 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.
  • Implement the InCallService API - facilitates development of a replacement for the device's default Phone/Dialer app. The InCallService alone does not have any calling capability and consists of the user-interface side of calling only. 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).
  • Implement both the InCallService and ConnectionService API - ideal if you wish to create your own ConnectionService based calling solution, complete with its own full user interface, while 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.

Interfaces

CallControlCallback CallControlCallback relays call updates (that require a response) from the Telecom framework out to the application.This can include operations which the app must implement on a Call due to the presence of other calls on the device, requests relayed from a Bluetooth device, or from another calling surface. 
CallEventCallback CallEventCallback relays call updates (that do not require any action) from the Telecom framework out to the application. 

Classes

Call Represents an ongoing phone call that the in-call app should present to the user. 
Call.Callback Defines callbacks which inform the InCallService of changes to a Call. 
Call.Details  
Call.RttCall A class that holds the state that describes the state of the RTT channel to the remote party, if it is active. 
CallAttributes CallAttributes represents a set of properties that define a new Call. 
CallAttributes.Builder Build an instance of CallAttributes. 
CallAudioState Encapsulates the telecom audio state, including the current audio routing, supported audio routing and mute. 
CallControl CallControl provides client side control of a call. 
CallEndpoint Encapsulates the endpoint where call media can flow 
CallRedirectionService This service can be implemented to interact between Telecom and its implementor for making outgoing call with optional redirection/cancellation purposes. 
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. 
CallScreeningService.CallResponse Information about how to respond to an incoming call. 
CallScreeningService.CallResponse.Builder  
Conference Represents a conference call which can contain any number of Connection objects. 
Conferenceable Interface used to identify entities with which another entity can participate in a conference call with. 
Connection Represents a phone call or connection to a remote endpoint that carries voice and/or video traffic. 
Connection.RttModifyStatus Provides constants to represent the results of responses to session modify requests sent via Call#sendRttRequest() 
Connection.RttTextStream Provides methods to read and write RTT data to/from the in-call app. 
Connection.VideoProvider Provides a means of controlling the video session associated with a Connection. 
ConnectionRequest Simple data container encapsulating a request to some entity to create a new Connection. 
ConnectionService An abstract service that should be implemented by any apps which either:
  1. Can make phone calls (VoIP or otherwise) and want those calls to be integrated into the built-in phone app. 
DisconnectCause Describes the cause of a disconnected call. 
GatewayInfo Encapsulated gateway address information for outgoing call. 
InCallService This service is implemented by an app that wishes to provide functionality for managing phone calls. 
InCallService.VideoCall Used to issue commands to the Connection.VideoProvider associated with a Call. 
InCallService.VideoCall.Callback The InCallService extends this class to provide a means of receiving callbacks from the Connection.VideoProvider. 
PhoneAccount Represents a distinct method to place or receive a phone call. 
PhoneAccount.Builder Helper class for creating a PhoneAccount. 
PhoneAccountHandle The unique identifier for a PhoneAccount. 
PhoneAccountSuggestion  
RemoteConference A conference provided to a ConnectionService by another ConnectionService through ConnectionService#conferenceRemoteConnections. 
RemoteConference.Callback Callback base class for RemoteConference. 
RemoteConnection A connection provided to a ConnectionService by another ConnectionService running in a different process. 
RemoteConnection.Callback Callback base class for RemoteConnection. 
RemoteConnection.VideoProvider RemoteConnection.VideoProvider associated with a RemoteConnection. 
RemoteConnection.VideoProvider.Callback Callback class used by the RemoteConnection.VideoProvider to relay events from the Connection.VideoProvider. 
StatusHints Contains status label and icon displayed in the in-call UI. 
TelecomManager Provides access to information about active calls and registration/call-management functionality. 
VideoProfile Represents attributes of video calls. 
VideoProfile.CameraCapabilities Represents the camera capabilities important to a Video Telephony provider. 

Exceptions

CallEndpointException This class represents a set of exceptions that can occur when requesting a CallEndpoint change. 
CallException This class defines exceptions that can be thrown when using Telecom APIs with OutcomeReceivers. 
QueryLocationException This class represents a set of exceptions that can occur when requesting a Connection#queryLocationForEmergency(long, String, Executor, OutcomeReceiver)