Twilio 2010-04-01 API Upgrade Guide

This guide covers the essential changes you will need to make to your application in order for it to work with the 2010-04-01 version of the Twilio API. Check out the changelog to get a full overview of all changes and new features.

Opt Into API Version 2010-04-01

• To initiate outbound calls or SMS messages using the new API you'll have to change the outbound URI of your requests to include '2010-04-01' as the version string.
• In order to handle inbound calls using the new API, set the API version number on a per-number basis using the phone numbers interface in your account portal.

Check Text-to-Speech Audio

In this API revision we introduced a new and much improved text-to-speech engine. Be sure to test all parts of your applications that rely on the <Say> verb, since interpretation of whitespace and punctuation in particular may have changed.

Update Call End Callbacks for Voice

By default the previous 2008-08-01 API revision had an automatic callback to your initial TwiML URL at the end of each call. With the new API, if you'd like to keep receiving call-end-callbacks you must specify a 'StatusCallback' URL on your incoming phone numbers and outgoing calls.

Change 'Caller' and 'Called' to 'From' and 'To'

We've updated the parameter names for clarity. Although the REST API will accept requests that use the old parameters, this feature is deprecated. Further, the TwiML API does not pass the old parameters to your app upon incoming calls, so you will need to update your application accordingly. Rename all instances of 'Caller' and 'Called' to 'From' and 'To' respectively.

Update Duration Parameter Names

We've updated the 'Duration' parameter across resources to make it less ambiguous. You'll need to do the following: * Rename the 'Duration' parameter within <Record> action handlers to 'RecordingDuration' * Rename the 'Duration' parameter within 'StatusCallback' (formerly call-end-callback) handlers to 'CallDuration' * Rename the 'Duration' parameter within <Dial> action handlers to 'DialCallDuration'

Update IncomingPhoneNumber Properties

We've updated the REST API's IncomingPhoneNumber resource properties to be more clear. You'll need to do the following: * Rename 'Url' to 'VoiceUrl' * Rename 'Method' to 'VoiceMethod' * Rename 'FallbackUrl' to 'VoiceFallbackUrl' * Rename 'FallbackMethod' to 'VoiceFallbackMethod'

Expect GMT Instead of Pacific Time

All the times that Twilio passes back to you are now GMT in RFC2822 format. previously times were reported as US Pacific.

'+' and country code syntax for all phone numbers

All phone numbers are now formatted with a '+' and country code e.g., +16175551212 (E.164 format). You will need to make sure you app is compatible with this number format.

Using JSON? Update for New Format with Pagination

We've added pagination and updated the formatting of our JSON representations, so if you're using it you'll need to make sure you update your code to match the new format.

Expect String Constants

To increase clarity we've updated the API to pass string constants instead of numbers for flags and status parameters in the REST API. Note especially that the constants 'true' and 'false' replace '1' and '0' for boolean parameters.

Outbound Call Response Updated

You'll need to update your app to receive 'CallStatus', 'Direction' and 'AnsweredBy' instead of DialStatus.

<Dial> Verb Status Changed

We've moved the name of second leg <Dial> status to 'DialCallStatus', replacing 'DialStatus'.

Expect Direction Property on SMS instead of Flags

To keep symmetry with calls, SMS messages now have a 'Direction' property which replaces the old 'Flags' property.