FAQ
Incoming Calls and Registration for Push Notifications
How can my App receive calls?
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(...). Twilio will send you a push notification through FCM (Firebase Cloud Messaging Service) or GCM(Google Cloud Messaging Service). Check our quickstart implementation for how it is done.
Can the App receive incoming VoIP calls while it's not running or in the background?
Yes! See the FAQ “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?
The device token must be registered every time it changes or if the device has not received a push notification for 1 year. We recommend you implement the following logic:
- InvokeVoice.register(...) the first time the App is launched
- Store the device token and the current time. This is necessary to determine if the device token has changed.
- Implement “FirebaseMessagingService” and check when the token is updated or invalidated via “onNewToken()” callback. Compare it to the token value stored in 2. If it has changed, invokeVoice.register(...) and store the new device token value.
- Check when [Voice.register(...) was last invoked. If it has been over 6 months, register the token again to not let it expire.
What's the difference between an Access Token and a Device Token?
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?
- Twilio Access Token supports authentication for multiple products, but you need to make sure that you are using
VoiceGrant
for the Programmable Voice SDK. - You might have used the incorrect API key/secret pair to create the Access Token. Please make sure you keep the API secret privately 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 you have expiry <= (86400 -1).
- The API keys/secrets are not sharable between main account and sub-accounts.
- Please make sure the Access Token has non-empty
identity
.
- Twilio Access Token supports authentication for multiple products, but you need to make sure that you are using
- Why am I not receiving any incoming call push notification although the SDK says it registered successfully?
- The Twilio Programmable Voice Android SDK requires
FCM SECRET
orFCM Server Key
to be able to send push notifications to signal arrival of an incoming call. You need to use these values to create a Push Credential. If thegoogle-services.json
used in your application is not the correct one associated with theFCM SECRET
orFCM Server Key
, notification will fail.
- The Twilio Programmable Voice Android SDK requires
- Make sure you do not exceed more than 10 active registrations for the same
identity
. Twilio will notify only most recent 10 registered device and the rest of the devices will not receive notification. - 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?
- 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.
- The Programmable Voice SDK requires a new token format called the Twilio Access Token for authentication. Please update your token vending endpoint to generate
Outbound Call
- Why am I not able to make calls even though I am using Access Token?
- Make sure you are using a valid
Account SID
, a validAPI signing key
and a validsecret
in the Access Token.
- Make sure you are using a valid
Push notifications
My phone has been off for a while and when I turn it back on, I get calls that were already hung up
Note: This does not apply to version 2.1. The push notification sent to this version will expire within 30 seconds.
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. However, 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 Generate a UTC based timestamp on the TwiML Application Server based on the Unix epoch in milliseconds.
var timeInMS = Date.now()
Step 2 Add this generated timestamp to the
Parameters can be sent to a callee by initiating a TwiML
<?xml version="1.0" encoding="UTF-8"?> <Response> <Dial answerOnBridge="false" callerId="client:alice"> <Client> <Identity>bob</Identity> <Parameter name="timestamp" value="1555825985" /> </Client> </Dial> </Response>
When the call invite push message arrives to the callee it will have the specified parameters.
Step 3 Get the timestamp from the bundle or message provided by FCM when it arrives to the Android application.
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.
Map<String, String> customParameters = new HashMap<>(); String query_pairs = data.get(“twi_params”); if (query_pairs != null) { final String[] pairs = query_pairs.split("&"); for (String pair : pairs) { final int idx = pair.indexOf("="); final String key; try { key = idx > 0 ? pair.substring(0, idx) : pair; final String value = idx > 0 && pair.length() > idx + 1 ? URLDecoder.decode(pair.substring(idx + 1).replaceAll("\\+", "%20"), "UTF-8") : null; customParameters.put(key, value); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } } }
3.X SDKs
When receiving the push notification from Twilio, you can obtain the parameter from CallInvite with the following:
Map<String, String> customParameters = callInvite.getCustomParameters(); String timestampString = customParameters.get(“timestamp”);
Step 4 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
// Get the timestamp from the customParameters map and the current device time String timestampString = customParameters.get(“timestamp”); long timestamp = Long.parseLong(timestampString); long currentTimestamp = System.currentTimeMillis(); // Compare the time difference if (currentTimestamp > timestamp + 60000) { // discard notification... } else { // display notification... }
Great tools and links
- jwt.io - decode and see what’s in your Access Token.
- Twilio Programmable Voice dashboard - view errors/warnings in real time.
How to file a support ticket or create a GitHub issue
We love feedback and questions especially those with helpful debugging information so we can diagnose and respond in time. When submitting issues or support tickets, it would be great if you add the following:
- 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, and 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 here on Github.
For general inquiries related to the Voice SDK you can file a support ticket.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.