Learn more with Workshops and Technical Sessions

Developer Conference for Communications

2010-04-01 API Changelog

This document provides an overview of the changes between Twilio API release 2010-04-01 and the previous 2008-08-01 release. The new release contains over 100 new features and improvements to the Voice, SMS and Phone Number APIs, many of which incorporate feedback from the community. Thanks!

We've created a simple upgrade guide that walks through the changes you'll need to make to your applications should you choose to move to the new API. Do note that you are NOT required to upgrade or change anything about your applications. If you do nothing, nothing will break. But you won't get to take advantage of all the new features the 2010 API has to offer.

Continued Support for API Version 2008-08-01

Existing applications running on the old 2008-08-01 API version will continue to operate without any changes and Twilio will continue to support API version 2008-08-01. If you do nothing, your application will continue to operate normally. If you opt to upgrade your application, it will require a few small tweaks to make it compatible and take advantage of the new features. Detailed changes are listed below.

Using Version 2010-04-01

To start using the new API, replace '2008-08-01' with '2010-04-01' in your REST URIs, or set the API version on a per-phone number basis using the phone numbers interface in your account portal. Setting the API version to '2010-04-01' on an incoming phone number means all incoming calls or SMS messages to that phone number will execute TwiML under the 2010-04-01 API revision. Similarly, by specifying '2010-04-01' in a REST API URI, all outgoing calls or SMS messages will execute under the 2010-04-01 API revision. There is no way to change the API version of a specific call or SMS once it has started.

Changes Summary

Detailed Changes

The Twilio phone number search and provisioning API lets developers programmatically search for and buy Twilio inbound local and toll-free phone numbers. The new API divides the process into two steps. The first step is to search for one or more phone numbers by performing an HTTP GET to the AvailablePhoneNumbers REST resource. The search API returns a list of Twilio incoming phone numbers that match a pattern, that are in certain area code (NPA) or exchange (NXX), or are in a specific geography. If no phone numbers that match the search term or terms are found, an empty list is returned.

The second step is to purchase a phone number from the search results list. This is done by performing an HTTP POST to the IncomingPhoneNumbers resource and passing the phone number to buy as the 'PhoneNumber' parameter. You may only purchase one phone number per HTTP request. Phone numbers are available on a first-come-first-served basis and are not reserved for any account. We recommend you purchase numbers shortly after searching to minimize the chance of losing the phone number you want.

Documentation references:

New Text-to-Speech Engine

The Twilio Text-to-Speech engine that powers the Twilio Say verb has been upgraded. The 'man' and 'woman' voice now have better pronunciation and handling of abbreviations in each of our supported languages. The old version of the TTS is available under the 2008-08-01 API.

Here is an example of TTS in the old API (2008-08-01) : old-TTS-2008-08-01.mp3

Here is an examlpe of TTS in the new API (2010-04-01) : new-TTS-2010-04-01.mp3

Be sure to test all parts of your applications that rely on the <Say> verb after moving to the 2010-04-01 API, since interpretation of whitespace and punctuation in particular may have changed.

Documentation references:

Ability to Reject incoming calls

When a phone number is set to the 2010-04-01 API (via the REST API or twilio.com account portal), the CallStatus for incoming calls starts as "ringing". Twilio waits to answer an incoming call until we see a <Play>, <Say>, <Gather>, <Record>, or <Dial> in the TwiML response. If the first verb in the TwiML is <Reject>, the call ends with a state busy or no-answer, depending on the attribute set. Your account will not be charged for rejected calls. Rejected is the default behavior. Otherwise, the call is answered, CallStatus is set to "in-progress" and the call proceeds normally. This primitive lets you implement blacklists and prevent abuse of incoming phone numbers. The Reject verb has no effect on outgoing calls.

For example, to reject an incoming call return this TwiML:


Documentation references:

New API to Hangup a Queued or In-progress Call

Using the REST API you can now hangup outgoing calls that are queued waiting to be initiated or you can hangup any in-progress call. Once a call has been created, just POST to the 'Status' parameter on the call instance resource with the value 'canceled' or 'completed'. Status=canceled will attempt to hangup calls that are queued or ringing but will not affect calls already in-progress. Status=completed will attempt to hangup a call even if it's already in-progress.

Documentation references:

Call end callback replaced by explicit StatusCallback parameter on IncomingPhoneNumbers and Calls

Did you find the call end callback for voice calls confusing? You are not alone. It served an important need -- notifying your application when a call was complete -- but because it always hit your initial URL, the implementation was confusing. In API release 2010-04-01 we've moved functionality of the call end call back to an optional StatusCallback parameter that you can can specify on an incoming phone number or on a REST API request to initiate an outgoing call.

The StatusCallback parameter works very similarly to the StatusCallback parameter on SMS messages, letting your application know when a call is marked busy, no-answer, or completed. If you do not explicitly specify StatusCallback on your phone number or with your outgoing call request you will not receive any notification from Twilio when the call ends.

Documentation references:

Unified DialStatus/CallStatus

The result of outbound API call attempts is now reported back via a combination of 'CallStatus', 'Direction' and 'AnsweredBy' instead of DialStatus.

CallStatus can be one of the following:

queuedthe call has not yet been placed
ringingthe call is currently ringing
in-progressthe call has been answered and is being billed
completedthe call was answered and is now complete
busythe caller received a busy signal
failedthe call couldn't be completed
no-answerthe call ended and was unanswered
canceledthe call was canceled via the API before it was answered

When a <Dial> 'action' handler is called, the status of the 2nd leg is reported in the 'DialCallStatus' parameter, replacing 'DialStatus'.

Documentation references:

All 2nd leg calls get their own CallSid (CallSegmentSid is removed)

We've removed the CallSegmentSid from 2nd leg calls. Instead, Twilio creates an entirely new CallSid for each 2nd leg call and sets its ParentCallSid to that of the first call. Now that every call has its own sid, you can use the REST API to redirect 2nd leg calls (which was previously impossible).

Documentation references:

REST API Outputs "More Better" JSON

We've overhauled the JSON response format for our REST API. The new format is less like an XML document mashed into JSON and more like a natural JSON document. And it includes paging information that the old format didn't display.

Old JSON Format:

{ "TwilioResponse": 
    {  "Calls": [
        {"Call": { "Sid": "CA1234...", ... }}, 
        { ... },

New JSON Format:

{  "page": 0, 
   "num_pages": 1,
   "page_size": 50,
   "total": 3,
   "start": 0,
   "end": 2, 
   "calls": [
       "sid": "CA1234...",
       "sid": "CA2222...",

Yep... more better!

Documentation references:

REST API now returns hypermedia links

We are happy to announce that the Twilio API is now 55.5773247% more RESTy. Every resource representation now includes a self-referencing URI, instance resource representations include sub-resource URIs, and list resource representations include next/previous page URIs. For an example, check out the GET response from the Calls list resource linked below.

Documentation references:

FallbackUrl and FallbackMethod supported on outgoing calls

FallbackUrl and FallbackMethod are now supported on both IncomingPhoneNumber records and on outgoing call requests to help provide high availability to your application. For more information on FallbackUrl please see here: http://www.twilio.com/docs/availability/availability.

Documentation references:

Disambiguated the 'Duration' parameter passed in TwiML

In the previous API release, it wasn't always clear what the 'Duration' passed as a TwiML parameter referred to. To differentiate the different uses, we've given each duration a unique name: 'RecordingDuration', 'CallDuration' and 'DialCallDuration'. Also, these durations are always represented in seconds.

New ability to delay answering calls

If the first verb in the first TwiML document fetched as part of an incoming call is <Pause>, Twilio will now delay answering the call for the number of seconds specified. This is useful in avoiding automated answering machine detection systems and other systems that sometimes prevented call forwarding.

Documentation references:

String constants replace numbers for all flags/status parameters in the REST API

Statuses and Flags displayed by the API are now meaningful text strings instead of arbitrary integer values. No more guessing as to what magic numbers mean, and more importantly no more bitwise fields to decipher!

New Direction and AnsweredBy parameters on calls

In the new API, we are introducing two new call attributes: 'Direction' and 'AnsweredBy'. 'Direction' is either 'inbound', 'outbound-api' or 'outbound-dial'. 'AnsweredBy' is either 'human', 'machine' or blank if an answering machine detection wasn't used.

'Direction' values:

inboundthe call was inbound to a Twilio number.
outbound-apithe call was initiated by the API.
outbound-dialthe call segment was initiated by a <Dial> verb.

'AnsweredBy' values:

machinethe call was answered by an answering machine.
humanthe call was answered by a human.

Documentation references:

New Direction property replaces Flags on SMS messages

To keep symmetry with calls, SMS messages now have a 'Direction' property. Possible values are below:

inboundthe SMS was inbound to a Twilio number.
outbound-apithe SMS was initiated by the API.
outbound-replythe SMS was initiated by an <Sms> verb in response to an incoming SMS.
outbound-callthe SMS was initiated by an <Sms> verb during a phone call.

Documentation references:

Caller and Called represented as To and From for voice calls

The parameters 'Caller' and 'Called' were easily confused for each other (shocking isn't it!). The 2010-04-01 API will now accept and return 'From' and 'To' to represent the call originator and destination. The API will still accept Caller/Called, but their use is deprecated and may not be supported in future versions.

Documentation references:

'+' and country code syntax for all phone numbers

All phone numbers (e.g. To, From, ForwardedFrom) are now formatted with a '+' and country code e.g., +16175551212 (E.164 format). E.164 is an ITU standard for representing phone numbers which is used around the world.

Documentation references:

All timestamps returned in GMT format

All times in parameters Twilio passes to your application are now given as GMT times in RFC 2822 format. Previously, times were reported as US Pacific.

Documentation references:

Url and Method renamed to VoiceUrl and VoiceMethod on phone numbers and sandbox

The properties Url, Method, FallbackUrl and FallbackMethod have been renamed VoiceUrl, VoiceMethod, VoiceFallbackUrl and VoiceFallbackMethod on incoming phone numbers and in the sandbox to clear up ambiguity with their SMS counterparts.

Documentation references:

CalledVia renamed to ForwardedFrom

While we were renaming parameters for clarity's sake, we changed 'CalledVia' to 'ForwardedFrom'. This was a previously undocumented parameter sent in a TwiML request for incoming calls. It represents the phone number of the forwarding device, rather than the Twilio phone number that was called. This parameter is set when Twilio receives a forwarded call and it's value depends on the providers forwarding the call.

This feature depends on support from the carrier forwarding call and will only work if the carrier passes Twilio the required information.

Documentation references:

Pass through raw Caller ID if not E.164

Caller IDs that cannot be normalized to E.164 format are passed through in their raw form. Previously, they were passed through as an empty string.

Documentation references:

TwiML parameters no longer passed at HTTP Headers

This fixes compatibility issues with non-compliant HTTP proxies and servers. Also, they were rarely used and increased request sizes, so we bid them farewell.

Deprecated the <Response> element's "version" attribute

Now that API version is set at the phone number level, we are deprecating the use of the version attribute on the <Response> element. The 2010-04-01 API will simply ignore this attribute if set in TwiML.