Skip to content

Phone Calls

Use this component when you want to build an app that would enable your users to Make, Receive and Notify Phone Calls from/in their cars.

How to implement Phone Calls functionality?

The following sections cover how you can get started using Phone Calls functionality. You can easily integrate the Phone Calls, by following these steps.

1. Dependencies

Open the build.gradle file for your project and add the following dependencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
dependencies {
    //for receiving notifications about incoming calls and ongoing call statuses
    implementation "com.telenav.sdk.vivid:android-sdk-phonecall-notification:${sdk_version}" 

    //for making phone calls
    implementation "com.telenav.sdk.vivid:android-sdk-phonecall-dial:${sdk_version}" 

    //for retrieving history
    implementation "com.telenav.sdk.vivid:android-sdk-phonecall-history:${sdk_version}" 
}

2. Receive Phone Calls and Notify Incoming Phone Calls

Important

In order to receive notifications, the app using the incoming (android-sdk-phonecall-notification) sdk needs to be set as Dialer app.

Permissions

Set the permision in order to be notified when the state of the call gets changed. (e.g Ringing -> Answered)

Permissions

1
<uses-permission android:name="android.permission.CALL_PHONE" />

Set the permision to read the phone number.

Permissions

1
<uses-permission android:name="android.permission.READ_CALL_LOG" />

3. Handle Phone Calls

In order to handle the phone calls, follow these steps:

1.Create a provider

The context Parameter represents the context of application.

1
val provider = PhoneCallProvider.create(context)

2.Add a listener to the 'IncomingCallManager'

Once a call is received, the 'onCallStatusUpdate' callback will be notified. The phoneCallListener Parameter is an object that implements the PhoneCallStatusListener interface.

1
provider.providePublisher().subscribe(phoneCallListener, PhoneCallTopic.ANY)

Register for Incoming Phone Call notifications.

The PhoneCallProvider is the entry point for Phone Call notifications.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Create a provider
val provider = PhoneCallProvider.create(app)

// Add a listener to the 'IncomingCallManager'.
// Once a call is received, the 'onCallStatusUpdate' callback will be notified.
var phoneCallListener = object : PhoneCallStatusListener {

        override fun onCallStatusUpdate(call: PhoneCallDetails) {
            val currentCallId = call.callId
            when (call.status) {
                TODO("handle all PhoneCallStatus states")
                        PhoneCallStatus.INCOMING -> {
                    TODO("handle INCOMING")
                }
            }
            TODO("keep track of the received call ids, in order to later answer, reject based on id")
        }

        override fun onCallError(error: PhoneCallError) {
            TODO("Handle error")
        }

        override fun onCallDurationUpdate(duration: Long) {
            TODO("Update UI with call duration (ms)")
        }
    }
// register for receiving 'incoming' call notification
provider.providePublisher().subscribe(phoneCallListener, PhoneCallTopic.ANY)

4. Interact with Phone Calls

Accept, Reject

Functionality is available in IncomingPhoneCallActionManager which is retrieved from the 'provider' instance.

Permissions

Set the permision in order to be notified when the state of the call gets changed. (e.g Ringing -> Answered)

Permissions

1
<uses-permission android:name="android.permission.CALL_PHONE" />

Set the permision to read the phone number.

Permissions

1
<uses-permission android:name="android.permission.READ_CALL_LOG" />

Retrieve the IncomingPhoneCallActionManager for accept and reject.

1
val incomingCallManager = provider.provideIncomingCallActionManager()

Answer

Answer a call by passing the id of the call. The callId is retrieved from the phoneCallListener#onCallStatusUpdate.

1
incomingCallManager.accept("currentCallId")

Reject

Reject a phone call by passing the id of the call. The id is retrieved from phoneCallListener#onCallStatusUpdate.

1
incomingCallManager.reject("currentCallId")

Reject a phone call with a message by passing the id of the call and the message we want to send to the caller. The id is retrieved from phoneCallListener#onCallStatusUpdate . If you call the api with an empty call id or an empty message, an IllegalArgumentException will appear.

1
incomingCallManager.rejectWithMessage("currentCallId", "I'm driving. Will call you later!")

Important

Always 'dispose' when provider is no longer needed, like when exiting the app. This frees caches, removes broadcast receivers, etc.:

1
provider.dispose()

Hold, Mute, End

This functionality is available in OngoingPhoneCallActionManager, retrieved from the provider instance.

Permissions

Set the permision in order to be notified when the state of the call gets changed. (e.g Ringing -> Answered)

Permissions

1
<uses-permission android:name="android.permission.CALL_PHONE" />

Set the permision to read the phone number.

Permissions

1
<uses-permission android:name="android.permission.READ_CALL_LOG" />

Info

Retrieve the OngoingPhoneCallActionManager and use it to act upon the ongoing call: end, mute, unmute, hold, untold etc.

1
val ongoingCallManager = provider.provideOngoingCallActionManager()

Hold

Put a call on hold. The callId Parameter represents the identifier for the call to be put on hold.

1
ongoingCallManager.hold("currentCallId")

Get back into a call. The callId Parameter represents the identifier for the call the user wants to get back into.

1
ongoingCallManager.unhold("currentCallId")

Mute

Mute the microphone for the current call. 

1
ongoingCallManager.mute()

Unmute the microphone for the current call.

1
ongoingCallManager.unmute()

Terminate

Terminate a call. The callId Parameter represents the identifier for the call to be terminated.

1
ongoingCallManager.end("currentCallId")

Important

Always 'dispose' when provider is no longer needed, like when exiting the app. This frees caches, removes broadcast receivers, etc.

1
provider.dispose()

5. Make a Phone Call

Permissions

This permission is required by the dial api.

Permissions

1
<uses-permission android:name="android.permission.CALL_PHONE" />

Phone dialing

Create a phone call dialer provider.

1
val phoneCallDialerProvider = PhoneCallDialerProvider.Factory.create(this).provideDialer()

Dial a phone number. It returns: [Success] if a call is successfully placed, [Error] if there was an error.

1
val result = phoneCallDialerProvider.dial("0707070707")

Dial a contact. It returns a PhoneCallResult as follows: [Success] if a call is successfully placed, [Error] if there was an error.

1
val result = phoneCallDialerProvider.dial(contact)

Places a call for the provided Contact and phone number type, for example Home or Work. Params: contact - a Contact object, numberType - an int. It returns a PhoneCallResult as follows: [Success] if a call is successfully placed, [Error] if there was an error.

1
val result = phoneCallDialerProvider.dial(contact, numberType)