Usage and Migration Guide for Twilio’s Ruby Helper Library 5.x
Deprecation notice: New functionality will only be added to the latest library, Ruby Helper Library 5.x. The old library (4.x) is deprecated and Twilio will no longer provide bug fixes. Support might ask you to upgrade before debugging issues.
The Twilio Ruby Helper Library has undergone a number of changes from version 4.x to 5.x. In this document, we explore the major changes to help you migrate to the new version as painlessly as possible. You can quickly jump to any of the topics using the contents panel to the right.
If you’re integrating Twilio in your Ruby app for the first time, you can skip straight to the install page.
Ruby version support
Note twilio-ruby 5.x only supports Ruby 2.0+ due to both 1.8.x and 1.9.x reaching End of Life.
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 anArray
that contains the requested resourceInstances
.
> @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 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
ページング
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.
エラー処理
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.
同様の変更はMessagingResponse
にも当てはまります。
And here’s a nested example:
APIリクエストのデバッグ
デバッグを容易にするため、ライブラリーでは内部的に使用されるリクエストおよびレスポンスのオブジェクトへのアクセスが行えるようになっています。 この機能はライブラリーに内蔵されている既定のHTTPクライアントに内蔵されています。
たとえば、下記のようにして直前のレスポンスのステータスコードを取得できます:
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
Where to find further help
All of the Quickstarts, Tutorials, and API Reference documentation will provide example code for both the older 4.x library and the new 5.x library. There are hundreds of samples just waiting for you to copy and paste.
The Twilio Ruby helper library is open source software. Please visit us on GitHub to view the source, open issues, or submit pull requests.
Finally, we are always ready to help! Just contact us directly for support.
ヘルプが必要ですか?
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。