Introducing Configurable Call Limits for Programmable Voice

August 02, 2021
Written by
Twilion
Reviewed by
Twilion
Twilion

Configurable Call Limits.png

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 four-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 four 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 one minute, all the way up to that 24 hour limit. You can even 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 effects of unwanted, long calls. For example, long duration limits may be necessary for conversational business use cases.

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.

In the left-hand navigation pane, under Develop, click on Voice > Settings > General. Scroll down to "24-Hour Maximum Call Duration" and click on the Disabled button/switch. (The button/switch text should now say Enabled.) Click Save at the bottom of the screen. Your maximum call duration has now been increased to 24 hours, effective immediately.

screenshot of the Voice Recording Encryption dashboard

If the 24-Hour Maximum Call Duration switch is Disabled, the time limit is four hours.

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 enabled 24-Hour Maximum Call Duration on your account, 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 time limit when you are creating a Twilio Voice Call:

  1. Using the Twilio Voice API Calls resource

  2. Using the Twilio Voice API Conference Participant resource

  3. Using the TwiML <Dial> verb

These settings will take precedence over the account-level Maximum Time Limit configuration as described above.

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 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 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

Using the Twilio Voice API Conference Participant resource

You can also generate an outbound Twilio Voice call when you add a Conference Participant via the the Voice API’s Conference Participant resource. 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 six 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 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

Using the TwiML <Dial> verb

The TwiML <Dial> verb has a timeLimit attribute for configuring the maximum call duration on an outbound Call. You can set a Call’s maximum duration in seconds to a value between 0 and 86400 seconds (24 hours):

Example for setting an eight-hour time limit on an outbound Call with TwiML:

<?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

Where ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is your Account SID, and CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX is the Call SID.

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 Twilio Console under Voice > Settings> General 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!