Usage and Migration Guide for Twilio’s Ruby Helper Library 5.x

Accessing resources

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

# New
call = @client.api.v2010.account.calls('CA123xxx').fetch
## OR
call = @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 in the example above, including .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 call fetch to get the actual instance of a Call. This is because .calls('CAxxx') returns a “Context”, on which we can call fetch 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'...>

Listing resources

There are now two ways to get a list of resources: list and stream.

• list does exactly what it used to: it returns an Array that contains the requested resource Instances.

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

• stream returns an Enumerable that can be passed to a block. It efficiently pages the list of resources for you and will pass either a limited number of instances to the block, or every resource in the entire list, if no limit is specified.

> @client.api.account.messages.stream(limit: 5).each {|m| puts m.sid}
MS111xxx
MS222xxx
MS333xxx
MS444xxx
MS555xxx

Paging

The library now automatically handles paging for you. With both list and stream, you can specify the number of instances you want to receive (limit), the maximum size you want each page fetch to be (page_size), and the maximum number of pages to fetch (page_limit). The library will then handle the task for you, as efficiently as possible.

@client.api.account.incoming_phone_numbers.stream(limit: 3000, page_size: 100).each do |number|
  puts number.phone_number
end

Proper types

twilio-ruby resources now serialize/deserialize appropriate types. For example, in 4.x, a Date would be represented as a String, leaving it up to you to serialize/deserialize strings into usable types. In 5.x, we deal with Time and Date objects automatically:

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

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

Configurable HTTP client

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)

The Faraday HTTP client library is used by default, so you can also plug in any Faraday adapter:

@client.http_client.adapter = :typhoeus

We have a complete example of creating a custom client in the Twilio helper library.

Error handling

The new library now provides the Twilio::REST::RestError class to help you manage errors:

# Old
begin
  call = @client.account.calls.get('CA123xxx')
rescue Twilio::REST::RequestError => e
  logger.log(e.message)
end

# New
begin
  call = @client.api.account.calls('CA123xxx').fetch
rescue Twilio::REST::RestError => e
  logger.log(e.message)
end

TwiML generation

You can now chain your calls to output simple TwiML. For example:

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new

def output_quick_polite_twiml():
  VoiceResponse.say('Hello!').hangup

There are now two response types, depending on what kind of response you want to output: VoiceResponse for all voice-related verbs and MessagingResponse for everything message related.

Voice verbs are available as VoiceResponse instance methods. You can set any attributes for those verbs using keyword arguments. All of them use underscore notation.

Verbs are no longer nested using with. Instead, append them to a parent.

The same changes apply to MessagingResponse:

And here’s a nested example:

Debugging API requests

To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.

For example, you can retrieve the status code of the last response like so:

require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# Put your own credentials here
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# Set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new(account_sid, auth_token)

@message = @client.messages.create(
  to: '+14158675309',
  from: '+14258675310',
  body: 'Ahoy!'
)

# Retrieve the status code of the last response from the HTTP client
puts @client.http_client.last_response.status_code