This is an upgrade guide for moving from 4.x to 5.x versions of thetwilio-ruby helper library.

Note: twilio-ruby 5.x only supports Ruby 2.0+ due to both 1.8.x/1.9.x reaching End of Life

# Oldcall=@client.account.calls.get('CA123xxx')

# Newcall=@client.api.v2010.account.calls('CA123xxx').fetch## ORcall=@client.api.account.calls('CA123xxx').fetch

The new library makes Twilio API subdomains (Lookups, Conversations, Monitor, etc.) first-class citizens. You can now also pin your interactions to the Twilio API to specific versions of that API (so here,.v2010. ensures we always talk to the 2010-04-01 version of the API). This allows you to migrate portions of your code to future versions independently without having to do a full upgrade when you update the library.

You'll also notice you have to callfetch at the end to get the actual instance of aCall. This is because.calls('CAxxx') returns a "Context", which we can thenfetch to retrieve an "Instance", with all of its properties attached. This allows for better network efficiency and makes it more clear when the library is actually performing HTTP interactions.

>workspace=@client.taskrouter.workspaces('WSxxx')#=> <WorkspaceContext ...>>workspace.fetch#=> <WorkspaceInstance status='active'...>

There are now 2 ways to get a list of resources:list andstream.

• list does exactly what it used to: it returns anArray that contains the Instances of resources.

>@client.api.account.messages.list#=> [#<MessageInstance ..>, #<MessageInstance ..>, ...]

• stream returns anEnumerable that can be passed to a block, it efficiently pages the list of resources for you and will passlimit amount of instances to the block (or every resource in the entire list, if nolimit is set).

>@client.api.account.messages.stream(limit:5).each{|m|putsm.sid}MS111xxxMS222xxxMS333xxxMS444xxxMS555xxx

The library now automatically handles paging for you! In bothlist andstream, you can specify the amount of instances you want to grab (limit), the maximum size you want each page fetch to be (page_size), and the maximum amount of pages to fetch (page_limit). The library will then handle the rest for you (as efficiently as possible)!

@client.api.account.incoming_phone_numbers.stream(limit:3000,page_size:100)do |number|putsnumber.phone_numberend

>@client.conversations.completed.list(page_size:100,page_limit:10).size#=> 1000

twilio-ruby resources now serialize/deserialize appropriate types. For example, in 4.x, a date would be represented as aString, leaving it up to you to serialize/deserialize strings into usable types. In 5.x, we deal withTime andDate objects:

# Oldfeedback=@client.account.calls.feedback_summary.create(start_date:'2016-01-01',end_date:'2016-01-05')feedback.start_date#=> "2016-01-01"

# Newfeedback=@client.api.account.calls.feedback_summary.create(start_date:Date.new(2016,1,1),end_date:Date.new(2016,1,5))feedback.start_date#=> #<Date 2016-01-01 ..>

• Twilio::TwiML::Response was split;Twilio::TwiML::VoiceResponse,MessagingResponse and others.
• Method names are now snake_cased (no longer TitleCased)
• dial/message methods no longer take a default arg

# Oldtwiml=Twilio::TwiML::Response.newdo |r|r.Dial(user.phone_number,callerId:twilio_number)end

# Newtwiml=Twilio::TwiML::VoiceResponse.newdo |r|r.dial(number:user.phone_number,caller_id:twilio_number)end

You can now plug your own HTTP client into the Twilio::REST client! Just make a wrapper that conforms to the Twilio::HTTP::HttpClient Interface. Then, pass an initialized object into the Twilio::REST::Client:

custom_client=MyCustomClient.new@client=Twilio::REST::Client.new('ACxxx','AUTHTOKEN',http_client:custom_client)

Faraday is used by default, so you can also plug in anyFaraday adapter:

@client.http_client.adapter=:typhoeus

There are new classes to rescue errors from. The new library now uses theTwilio::REST::RestError class.

# Oldbegincall=@client.account.calls.get('CA123xxx')rescueTwilio::REST::RequestError=>elogger.log(e.message)end

# Newbegincall=@client.account.calls('CA123xxx').fetchrescueTwilio::REST::RestError=>elogger.log(e.message)end