Introducing Configurable Call Limits for Programmable Voice

Businesses throughout the globe use Twilio’s Programmable Voice platform to build conversations anywhere; you can make, receive, and monitor calls around the world using the proven Voice API and global Super Network that millions of developers rely on. These added capabilities allow you to add flexibility and intelligence to your customer interactions, and in doing so, offer better services and experiences to your customers.

If you’ve ever found yourself wanting more time for your Twilio voice calls, or the ability to better configure time limits depending on a call, we have some awesome news!

Historically, Twilio has had a hard-coded 4-hour call limit for all Voice calls. Often, this is plenty, but we’ve heard from you that the ability to make this time limit longer and more configurable would solve a world of problems. So, we did it!

With this release, we’ve extended the maximum Voice call duration on Programmable Voice calls from just 4 hours to a whopping 24 hours. We’ve also added the ability to set the maximum duration for individual calls to a value that works best for you. You can use any value between just 1 minute, all the way up to that 24 hour limit and can even easily change or update that limit on active calls!

You want the Call Limit that is right for you

In your day to day work, there may be many reasons why you need both short and long limits on call durations:

• Short duration limits can mitigate the effect of unwanted long calls:
  • “Runaway” calls due to equipment or network issues
  • Broadcast/Voicemail scenarios
  • Fraud
• Long duration limits are necessary for numerous conversational business use-cases:
  • Telemedicine, Insurance, Travel, Financial, and other Support/Call Centers
  • Incident/Disaster Management with open-ended timeframes
  • Earnings and Guidance calls for public enterprises can be extremely long

Now, Twilio provides you the control to implement your own custom limits, in order to meet your customers’ needs. Short calls, long calls, or anywhere in between, we’ve got you covered!

How does it work?

Default Call Limits can be extended to 24 hours on a per-account basis in your Twilio Console. You can also set or adjust the Call Limit on a per-call basis using the Voice API or TwiML.

Enable the Extended Maximum Limit for your account

Configurable Call Limits are Live now in your account’s Console, under your Programmable Voice “Settings” page. Just flip the switch to turn it on, and your maximum call duration is increased to 24 hours, effective immediately.

If you leave this switch Disabled, the Time Limit remains at 4 hours, so your current Twilio functionality will not change unless you want it to. NOTE: Trial accounts will still be limited to a maximum call length of 10 minutes, no matter how this setting is configured.

Configure Maximum Call Duration on a new call

Now that you have set your account’s Maximum Call Duration policy, what if you want to set a different time limit on a specific call? You can do that too! There are three ways you can set the timeLimit when you are creating a Twilio Voice call; these settings will take precedence over the Account-level Maximum Time Limit you configured as described above (10 minutes, 4 hours, or 24 hours, depending on your account and configuration).

Using the Twilio Voice API Calls resource

You can generate an outbound Twilio Voice call using the API’s Call resource; we have added a TimeLimit parameter to the Calls resource, so you can set the maximum duration in seconds.

Example for making an outbound-api call with a maximum duration of 10 hours:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
--data-urlencode "Twiml=<Response><Say>Ahoy there$EXCLAMATION_MARK</Say></Response>" \
--data-urlencode "To=+15558675310" \
--data-urlencode "From=+15552223214" \
--data-urlencode "TimeLimit=36000" \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

If you set the timeLimit to a value below 60 seconds or above the account’s Maximum Time Limit setting (10 minutes/4 hours/24 hours), you will get an error response:

• ‘13216 - Invalid timeLimit value’

Using the Twilio Voice API Conference Participant resource

You can also generate an outbound Twilio Voice call when you use the API’s Conference Participant resource to Add a participant. As with the Call resource, we have added a TimeLimit parameter, so you can set the maximum duration in seconds.

Example for adding a Participant with a maximum call duration of 6 hours:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conferences/CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants.json \
--data-urlencode "From=+14155551212" \
--data-urlencode "To=+14158675309" \
--data-urlencode "TimeLimit=21600" \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

If you set the timeLimit to a value below 60 seconds or above the account’s Maximum Time Limit setting (10 minutes/4 hours/24 hours), you will get an error response:

• ‘13216 - Invalid timeLimit value’

Using the TwiML <Dial> verb

The TwiML <Dial> verb has an attribute you can use to set the maximum duration on an outbound-dial call; this is the timeLimit attribute. This attribute allows you to set a call’s maximum duration in seconds to a value between 0 and 86400 seconds (24 hours):

For example, if you wanted to Dial a call with a limit of 8 hours, you would use TwiML similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial timeLimit="28800">415-123-4567</Dial>
</Response>

If you set the timeLimit to a value below zero or above the account’s Maximum Time Limit setting (10 minutes/4 hours/24 hours), you will get an error response:

• ‘13216 - Invalid timeLimit value’

Change Maximum Call Duration on an active call

The Twilio Voice API’s Call resource will also allow you to update the maximum call duration on an active call, using the same timeLimit parameter and an active call SID.

For example, if you wanted to change the maximum duration on an active call to 10 hours:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
--data-urlencode "timeLimit=36000" \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

This will allow you to either extend or reduce the maximum duration on an active call. If you set the timeLimit to a value below the current duration, or above the account’s Maximum Time Limit setting (10 minutes/4 hours/24 hours), you will get an error response:

• ‘13216 - Invalid timeLimit value’

What happens when my call reaches the Call Limit I have configured?

If your call reaches the default time limit you have configured, or the limit you have set for that specific call, whichever is shorter, the call will be disconnected.

Monitoring tools can help you tune your settings

If you have a call that does reach the Call Limit you configured, a Twilio Debugger alert will fire to let you know.

For example, if you have not configured a shorter call-specific timeLimit parameter for your call, when the call reaches your account’s Maximum Time Limit setting (10 minutes/4 hours/24 hours), it will be terminated, and you will receive the following alert:

• ‘32015 - Call is terminated due to exceeding account maximum call duration’

If you have configured a shorter call-specific timeLimit value, and that limit is reached, the call will be terminated, and you will receive the following alert:

• ‘32015 - Call is terminated due to exceeding configured maximum call duration (timeLimit)’

Additionally, the disconnect reason will be available as part of the Voice Insights data logged for the call.

These tools will allow you to compile data on how many calls are hitting the configured time limits, which will let you tune your Call Limit settings accordingly.

How do I get started?

The option to extend your Call Limits is now live in your Programmable Voice Settings console, and the timeLimit parameter is available for you to use in your applications using the Programmable Voice API and TwiML. If you have any questions about this, or Twilio Programmable Voice in general, please contact us.

We can’t wait to see what you build!