Skip to contentSkip to navigationSkip to topbar
Rate this Page:

Upgrade from Twilio's v2008 API


Ready to migrate from Twilio's deprecated v2008 API to the latest version? This guide covers the essential 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

opt-into-api-version-2010-04-01 page anchor
  • 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.

Update the API Version of a Phone Number

update-the-api-version-of-a-phone-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.incomingPhoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({apiVersion: '2010-04-01'})
_10
.then(incoming_phone_number => console.log(incoming_phone_number.friendlyName));

Output

_41
{
_41
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"address_requirements": "none",
_41
"address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"api_version": "2010-04-01",
_41
"beta": false,
_41
"capabilities": {
_41
"voice": true,
_41
"sms": false,
_41
"mms": true,
_41
"fax": false
_41
},
_41
"date_created": "Thu, 30 Jul 2015 23:19:04 +0000",
_41
"date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",
_41
"emergency_status": "Inactive",
_41
"emergency_address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"emergency_address_status": "registered",
_41
"friendly_name": "(808) 925-5327",
_41
"identity_sid": "RIXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"origin": "origin",
_41
"phone_number": "+18089255327",
_41
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"sms_application_sid": "",
_41
"sms_fallback_method": "POST",
_41
"sms_fallback_url": "",
_41
"sms_method": "POST",
_41
"sms_url": "",
_41
"status_callback": "",
_41
"status_callback_method": "POST",
_41
"trunk_sid": null,
_41
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
_41
"voice_application_sid": "",
_41
"voice_caller_id_lookup": true,
_41
"voice_fallback_method": "POST",
_41
"voice_fallback_url": null,
_41
"voice_method": "POST",
_41
"voice_url": null,
_41
"voice_receive_mode": "voice",
_41
"status": "in-use",
_41
"bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_41
}


Check your Text-to-Speech Audio

check-your-text-to-speech-audio page anchor

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

update-call-end-callbacks-for-voice page anchor

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'

change-caller-and-called-to-from-and-to page anchor

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

update-duration-parameter-names page anchor

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

update-incomingphonenumber-properties page anchor

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

expect-gmt-instead-of-pacific-time page anchor

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


Use '+' and country code syntax for all phone numbers

use--and-country-code-syntax-for-all-phone-numbers page anchor

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

using-json-update-for-a-new-format-with-pagination page anchor

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.


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

outbound-call-response-updated page anchor

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


<Dial> verb status changed

dial-verb-status-changed page anchor

We've moved the name of the 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'

expect-direction-property-on-sms-instead-of-flags page anchor

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.


Rate this Page: