Skip to content

Most visited

Recently visited

navigation

Self-Managed ConnectionServices

The self-managed ConnectionService API is ideal for developers of standalone calling apps which wish to use their own custom user interface for their calls rather than relying on the default Phone app. 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. It also manages audio routing and focus for you.

Calling Constraints

The ensure a consistent and simple calling experience for the user, the Telecom framework enforces some constraints for calling on the device. For example purposes, suppose the user has installed two calling apps which implement the self-managed ConnectionService API, FooTalk and BarTalk.

How the Self-Managed ConnectionService API Fits In

Making use of the self-managed ConnectionService API in your call flow involves interacting with the Telecom APIs. The following sections describe common scenarios you will encounter, and how your app should interact with and respond to the Telecom APIs.

Incoming Calls When There are No Calls in Other Apps

This section describes how to handle an incoming call where none of the constraints mentioned in Calling Constraints apply. This means that there are no ongoing calls, or the only ongoing calls are in your app.

  1. Your app receives a new incoming call using its usual means.
  2. Use addNewIncomingCall(PhoneAccountHandle, Bundle) to inform Telecom of the new incoming call.
  3. Telecom binds to your app's ConnectionService implementation and requests a new instance of Connection representing the new incoming call using onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. Telecom informs your app via onShowIncomingCallUi() that it should show its incoming call user interface.
  5. Your app shows its incoming UI using a Notification with associated full-screen Intent. (see onShowIncomingCallUi() for more information).
  6. Call setActive() if the user accepts the incoming call, or setDisconnected(android.telecom.DisconnectCause) and destroy() and specify REJECTED if the user rejects the incoming call.

Note: This is the first edition of the Self-Managed ConnectionService API. Future enhancements are planned to remove some of these restrictions and to add additional functionality such as the ability to write calls to the system call log.

Incoming Call When There are Calls in Other Apps

This section describes how to handle an incoming call where there are ongoing calls in another calling app. As mentioned in the calling constraints, Telecom will display the incoming call UI for your incoming call in this case.

  1. Your app receives a new incoming call using its usual means.
  2. Use addNewIncomingCall(PhoneAccountHandle, Bundle) to inform Telecom of the new incoming call.
  3. Telecom binds to your app's ConnectionService implementation and requests a new instance of Connection representing the new incoming call using onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. Telecom displays the incoming call UI for your incoming call.
  5. If the user accepts the call, Telecom calls onAnswer(int). You should call setActive() to indicate to Telecom that the call is now connected.
  6. If the user rejects the call, Telecom calls onReject(). You should call setDisconnected(android.telecom.DisconnectCause) and destroy() and specify REJECTED as the DisconnectCause.

Outgoing Calls

This section describes how your app should handle placing outgoing calls. As mentioned in calling constraints, your app may or may not be permitted to place an outgoing call at the current time. The Telecom APIs will inform your app whether it can place an outgoing call.

  1. The user initiates an outgoing call within your app.
  2. Use placeCall(android.net.Uri, android.os.Bundle) to inform Telecom of the new outgoing call. The Uri is the address the call is being placed to. For regular phone numbers, use the {@code tel:} URI scheme. In the Bundle, specify the PhoneAccountHandle of your Self-Managed ConnectionService in the EXTRA_PHONE_ACCOUNT_HANDLE extra. If the outgoing call is a video call, specify STATE_BIDIRECTIONAL in the EXTRA_START_CALL_WITH_VIDEO_STATE extra. Note: By default, Telecom routes video calls to the speakerphone.
  3. Telecom binds to your app's ConnectionService implementation.
  4. If your app is not able to place an outgoing call, Telecom calls onCreateOutgoingConnectionFailed(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) to inform your ConnectionService that the call cannot be placed at the current time. Your app should inform the user that the call cannot be placed.
  5. If you app is able to place an outgoing call, Telecom calls onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). Your app should return an instance of your Connection class to represent the new outgoing call. See below for more information on what properties you should set on the Connection.
  6. When the outgoing call has been connected, call setActive() to inform Telecom that the call is now active.

Ending a Call

When a call is ended, call setDisconnected(android.telecom.DisconnectCause) and destroy(). If the call ended because the user terminated the call, use LOCAL. If the call ended because the other party terminated the call, use REMOTE.

Implementing the Self-Managed ConnectionService API

Manifest Changes and Permissions

In your app's manifest, declare that your app uses permission MANAGE_OWN_CALLS.

See the <uses-permission> reference for more information about declaring application permissions.

In your app's manifest, declare a service entry for your self-managed ConnectionService. In order for Telecom to bind to your service, it must require the BIND_TELECOM_CONNECTION_SERVICE permission. For example:

    <service android:name="com.example.MyConnectionService"
        android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
        <intent-filter>
            <action android:name="android.telecom.ConnectionService" />
        </intent-filter>
    </service>
  

See the <service> reference for more information about declaring services.

ConnectionService Implementation

Your ConnectionService implementation should override the following methods in the ConnectionService API:

Connection Implementation

Your app should create an extension of the Connection class to represent the calls in your app. You should override the following methods in your implementation:

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)