Upgrade from Twilio's v2008 API

Ready to migrate from Twilio's deprecated v2008 API to the latest version? This guide covers the essential the changes you'll need to make to your applications to get them onto Twilio's current API (version 2010-04-01).

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.
• To handle inbound calls using the Version 2010-04-01 API, you can set the api_version on a per-number basis using the REST API.

Check your 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 the interpretation of whitespace and punctuation, in particular, may have changed. See this Text-to-Speech guide for more information.

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.

If you'd like to keep receiving call-end-callbacks with the current API, you must specify a StatusCallback URL on your incoming phone numbers and outgoing calls. Learn more by reading about ending a call with callback requests.

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

Rename all instances of Caller and Called to From and To respectively.

We've updated these parameter names for clarity. Although the REST API will accept requests that use the old parameters, this feature is deprecated. For the full list of available parameters, check out the full API reference documentation for the Call resource.

Note that the TwiML API does not pass the old parameters to your app upon incoming calls, so you will need to update your application accordingly.

Update duration parameter names

We've updated the Duration parameter across resources to make it less ambiguous.

You'll need to do the following:

1. Rename the Duration parameter within <Record>action handlers to RecordingDuration
2. Rename the Duration parameter within StatusCallback (formerly call-end-callback) handlers to CallDuration
3. 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:

1. Update the ApiVersion (see above)
2. Rename Url to VoiceUrl
3. Rename Method to VoiceMethod
4. Rename FallbackUrl to VoiceFallbackUrl
5. Rename FallbackMethod to VoiceFallbackMethod

Expect GMT instead of Pacific Time

All times that Twilio passes back to you are now GMT in RFC2822 format.

Use '+' 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 all phone numbers in your app are compatible with this number format.

Using JSON? Update for a 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 that the constants true and false replace 1 and 0 for boolean parameters.

Outbound call response updated

You'll need to update your Programmable Voice 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.

Read more about DialCallStatus in the TwiML <Dial> documentation.

Expect 'Direction' property on SMS instead of 'Flags'

SMS messages now have a Direction property which replaces the old Flags property.

For more information, see the full API reference documentation for the Message resource.