Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Voice Android SDK FAQ



Incoming Calls and Registration for Push Notifications

incoming-calls-and-registration-for-push-notifications page anchor

How can my App receive calls?

how-can-my-app-receive-calls page anchor

To be able to receive incoming calls, you need to setup your push certificate in the Console and your app needs to register for incoming calls using Voice.register(...)(link takes you to an external page). Twilio will send you a high-priority push notification through FCM (Firebase Cloud Messaging Service). Check our quickstart implementation(link takes you to an external page) for how it is done.

GCM (Google Cloud Messaging Service) was deprectated by Google on April 10, 2018. If you are currently using GCM, please migrate to FCM. GCM issues are not supported at this time.

Can the App receive incoming VoIP calls while it's not running or in the background?

can-the-app-receive-incoming-voip-calls-while-its-not-running-or-in-the-background page anchor

Yes! See How can my App receive calls to register for incoming calls. Once the app is registered, it will receive incoming call push notifications even when it's in the background or not running.

How often should I register my device token?

how-often-should-i-register-my-device-token page anchor

The device token must be registered every time it changes or if the device has not received a push notification for one year. We recommend you implement the following logic:

  1. Invoke Voice.register(...)(link takes you to an external page) the first time the App is launched.
  2. Store the device token and the current time. This is necessary to determine if the device token has changed.
  3. Implement FirebaseMessagingService and check when the token is updated or invalidated via onNewToken() callback. Compare it to the token value stored in step two, above. If it has changed, invoke Voice.register(...)(link takes you to an external page) and store the new device token value.
  4. Check when Voice.register(...)(link takes you to an external page) was last invoked. If it has been over 6 months, register the token again so that it does not expire.

What's the difference between an Access Token and a Device Token?

whats-the-difference-between-an-access-token-and-a-device-token page anchor

An Access Token is required to access Twilio's services. A device token is a token that identifies the device to receive a push notification.

I've created an Access Token vending endpoint, but why do I keep failing to register for incoming call push notifications?

ive-created-an-access-token-vending-endpoint-but-why-do-i-keep-failing-to-register-for-incoming-call-push-notifications page anchor

Below are several troubleshooting steps to make sure you have set up your application to receive push notifications:

  • Make sure that you are using a VoiceGrant . Twilio Access Token supports authentication for multiple products, but you must use a VoiceGrant with the Programmable Voice SDK.
  • You might have used the incorrect API key and secret pair to create the Access Token. Make sure you keep the API secret private once the API key is created, and use both the API key and secret to create the Access Token.
  • The maximum expiry duration allowed by Twilio is 24 hours, which equals to 86400 seconds. Please make sure that your token expiry is <= (86400 - 1).
  • API keys/secrets are not sharable between main account and sub-accounts . Make sure you are generating tokens using the correct API key and secret for your account.
  • Please make sure the Access Token has non-empty identity .

Why am I not receiving any incoming call push notifications although the SDK says it registered successfully?

why-am-i-not-receiving-any-incoming-call-push-notifications-although-the-sdk-says-it-registered-successfully page anchor

Below are troubleshooting steps if you are not receiving incoming call push notifications even if the SDK is successfully registered:

  • The Twilio Programmable Voice Android SDK requires FCM SECRET or FCM Server Key to send push notifications to signal the arrival of an incoming call. You need to use these values to create a Push Credential(link takes you to an external page) . If the google-services.json file used in your application is not the correct one associated with the FCM SECRET or FCM Server Key , notifications will fail.
  • Make sure you do not exceed more than 10 active registrations for the same identity . Twilio will notify only most recent 10 registered devices, and the rest of the devices will not receive notifications.

I was using the Android TwilioClient 1.2 SDK and just migrated to the Programmable Voice SDK. Why am I getting "Authentication error" using my Capability Token?

i-was-using-the-android-twilioclient-12-sdk-and-just-migrated-to-the-programmable-voice-sdk-why-am-i-getting-authentication-error-using-my-capability-token page anchor

The Programmable Voice SDK requires a new token format called the Twilio Access Token for authentication. Please update your token vending endpoint to generate Access Tokens for your application.


Why am I not able to make calls even though I am using Access Token?

why-am-i-not-able-to-make-calls-even-though-i-am-using-access-token page anchor

Make sure the values for Account SID, API signing key, and secret in the Access Token are all valid.


Will incoming call push notifications wake an Android device on Doze mode?

will-incoming-call-push-notifications-wake-an-android-device-on-doze-mode page anchor

Yes. Push notifications for incoming calls are always sent with high priority. If the device has entered Doze mode, it should wake with the incoming notification delivery. See more about Doze mode and high-priority delivery here(link takes you to an external page).

My phone has been off for a while and when I turn it back on, I get calls that were already hung up

my-phone-has-been-off-for-a-while-and-when-i-turn-it-back-on-i-get-calls-that-were-already-hung-up page anchor

Note: This does not apply to version 2.1 or higher. The push notification sent to those versions will only be delivered if the device is reachable when the call is placed.

Twilio Voice SDKs use push notifications (APNS, FCM/GCM) as a mechanism to notify the callee of an incoming call. However, a problem presents itself when the callee's device is offline or not reachable: the push notification services cache the notification and re-attempt delivery at a much later time. The delayed notification may arrive after the call has already been terminated. The callee's device will briefly alert the user of a call that has already terminated, leading to a poor user experience.

Twilio plans to address this issue in a later release. In the meantime, the following is a proposal for a work around you can implement to avoid the poor user experience.

The following 4 step proposal allows an app developer to use time information as an additional criteria to determine whether or not to display a call notification to the user.

Step 1

step-1 page anchor

Generate a UTC based timestamp on the TwiML Application Server based on the Unix epoch in milliseconds.


_10
var timeInMS = Date.now()

Add this generated timestamp to the <Dial> used to reach the callee.

Parameters can be sent to a callee by initiating a TwiML <Dial> verb. Use the <Parameter> attribute to specify your key/value parameters as shown below. The value shown below is an example of a timestamp obtained in Step 1. You must pass the value as string.


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Dial answerOnBridge="false" callerId="client:alice">
_10
<Client>
_10
<Identity>bob</Identity>
_10
<Parameter name="timestamp" value="1555825985" />
_10
</Client>
_10
</Dial>
_10
</Response>

When the call invite push message arrives to the callee, it will have the specified parameters.

Get the timestamp from the bundle or message provided by FCM when it arrives to the Android application. The method for doing this varies based on which version of the SDK you are using.

2.X SDKs

When receiving the push notification from Twilio, you can obtain the parameter from the bundle or message. The parameters are provided by FCM payload as the key: twi_params. The following shows how you can parse the contents of the data to get a map of the parameters you passed into the Dial. The "data" variable is the map provided by FCM.


_16
Map<String, String> customParameters = new HashMap<>();
_16
String query_pairs = data.get(“twi_params”);
_16
if (query_pairs != null) {
_16
final String[] pairs = query_pairs.split("&");
_16
for (String pair : pairs) {
_16
final int idx = pair.indexOf("=");
_16
final String key;
_16
try {
_16
key = idx > 0 ? pair.substring(0, idx) : pair;
_16
final String value = idx > 0 && pair.length() > idx + 1 ? URLDecoder.decode(pair.substring(idx + 1).replaceAll("\\+", "%20"), "UTF-8") : null;
_16
customParameters.put(key, value);
_16
} catch (UnsupportedEncodingException e) {
_16
e.printStackTrace();
_16
}
_16
}
_16
}

3.X SDKs

When receiving the push notification from Twilio, you can obtain the parameter from CallInvite with the following:


_10
Map<String, String> customParameters = callInvite.getCustomParameters();
_10
String timestampString = customParameters.get(“timestamp”);

Compare the UTC based timestamp to the UTC time on the device and discard the notification if the device time is significantly later than the timestamp generated by the server.

Android


_11
// Get the timestamp from the customParameters map and the current device time
_11
String timestampString = customParameters.get(“timestamp”);
_11
long timestamp = Long.parseLong(timestampString);
_11
long currentTimestamp = System.currentTimeMillis();
_11
_11
// Compare the time difference
_11
if (currentTimestamp > timestamp + 60000) {
_11
// discard notification...
_11
} else {
_11
// display notification...
_11
}


How to file a support ticket or create a GitHub issue

how-to-file-a-support-ticket-or-create-a-github-issue page anchor

We love feedback and questions, especially those with helpful debugging information so we can diagnose and respond in a timely manner. When submitting issues or support tickets, please add the following information:

  • Description: what are you trying to achieve, what steps did you take, and what issue did you have.
  • SDK version
  • SDK verbose log: SDK logs are always the best for the team to debug. Configure the SDK log level, set it to DEBUG : Voice.setLogLevel(LogLevel.DEBUG)
  • Twilio account SID
  • Twilio call SID

When you have gathered all this helpful information, please file any issues you find on Github.

For general inquiries related to the Voice SDK you can file a support ticket.


Rate this page: