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).
- 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 theapi_version
on a per-number basis using the REST API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateIncomingPhoneNumber() {11const incomingPhoneNumber = await client12.incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({ apiVersion: "2010-04-01" });1415console.log(incomingPhoneNumber.accountSid);16}1718updateIncomingPhoneNumber();
Response
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"address_requirements": "none",4"address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"api_version": "2010-04-01",6"beta": false,7"capabilities": {8"voice": true,9"sms": false,10"mms": true,11"fax": false12},13"date_created": "Thu, 30 Jul 2015 23:19:04 +0000",14"date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",15"emergency_status": "Inactive",16"emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"emergency_address_status": "registered",18"friendly_name": "(808) 925-5327",19"identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",20"origin": "origin",21"phone_number": "+18089255327",22"sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",23"sms_application_sid": "",24"sms_fallback_method": "POST",25"sms_fallback_url": "",26"sms_method": "POST",27"sms_url": "",28"status_callback": "",29"status_callback_method": "POST",30"trunk_sid": null,31"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",32"voice_application_sid": "",33"voice_caller_id_lookup": true,34"voice_fallback_method": "POST",35"voice_fallback_url": null,36"voice_method": "POST",37"voice_url": null,38"voice_receive_mode": "voice",39"status": "in-use",40"bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",41"subresource_uris": {42"assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"43}44}
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.
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.
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.
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 toRecordingDuration
- Rename the
Duration
parameter withinStatusCallback
(formerlycall-end-callback
) handlers toCallDuration
- Rename the
Duration
parameter within<Dial>
action handlers toDialCallDuration
We've updated the REST API's IncomingPhoneNumber resource properties to be more clear.
You'll need to do the following:
- Update the
ApiVersion
(see above) - Rename
Url
toVoiceUrl
- Rename
Method
toVoiceMethod
- Rename
FallbackUrl
toVoiceFallbackUrl
- Rename
FallbackMethod
toVoiceFallbackMethod
All times that Twilio passes back to you are now GMT in RFC2822 format.
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.
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.
You'll need to update your Programmable Voice app to receive CallStatus
, Direction
and AnsweredBy
instead of DialStatus
.
We've moved the name of the second leg <Dial>
status to DialCallStatus
, replacing DialStatus
.
Read more about DialCallStatus in the TwiML <Dial> documentation.
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.