The Twilio Ruby Helper Library
The twilio-ruby helper library lets you write Ruby code to make HTTP requests to the Twilio API. This library is open source, so if you find a feature missing or a bug, we encourage you to contribute back to the twilio-ruby project hosted on GitHub.
Install the Library
The easiest way to install twilio-ruby is from RubyGems.
gem install twilio-ruby
Manual Installation
Or, you can clone the source code for twilio-ruby, and install the library from there.
"Permission Denied"
If the command line gives you a big long error message that says Permission
Denied in the middle of it, try running the above commands with sudo, ex.
sudo gem install twilio-ruby.
Testing your installation
Test creating an SMS using your test credentials from https://twilio.com/console/settings, from a magic number to any number like so:
require 'twilio-ruby'
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Your Test Account SID from www.twilio.com/console/settings
auth_token = "your_auth_token" # Your Test Auth Token from www.twilio.com/console/settings
@client = Twilio::REST::Client.new account_sid, auth_token
message = @client.messages.create(
body: "Hello from Ruby",
to: "+12345678901", # Replace with your phone number
from: "+15005550006") # Use this Magic Number for creating SMS
puts message.sid
If you get a message SID in the output, you know you've successfully created a message with your test credentials. You will neither be charged nor receive an actual SMS in the "to" number.
It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out How to Set Environment Variables for more information.
Using the Gem
Try the Ruby quickstarts and refer to the open-source twilio-ruby specific documentation for details about the methods and classes contained in the library. Here are some simple examples of how to use the gem.
Authenticate the Client
require 'twilio-ruby'
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
@client = Twilio::REST::Client.new account_sid, auth_token
Create a New Record
require 'twilio-ruby'
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' # Your Test Account SID from www.twilio.com/console/settings
auth_token = 'your_auth_token' # Your Test Auth Token from www.twilio.com/console/settings
# Initialize Twilio Client
@client = Twilio::REST::Client.new(account_sid, auth_token)
@call = @client.calls.create(
url: 'http://demo.twilio.com/docs/voice.xml',
to: '+14155551212', #Replace with your phone number
from: '+15005550006' #User our Magic number to create test calls from
)
puts @call.sid
You will neither be charged, nor create a real call. But if you get a call SID in the output, you are good.
Get Existing Record
require 'twilio-ruby'
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
# Initialize Twilio Client
@client = Twilio::REST::Client.new(account_sid, auth_token)
@call = @client.api.calls('CA42ed11f93dc08b952027ffbc406d0868').fetch
puts @call.to
Iterate Through Records
require 'twilio-ruby'
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
# Initialize Twilio Client
@client = Twilio::REST::Client.new(account_sid, auth_token)
@client.calls.list
.each do |call|
puts call.direction
end
The library automatically handles paging for you. Collections, such as calls and messages, have list and stream methods that page under the hood. With both list and stream, you can specify the number of records you want to receive (limit) and the maximum size you want each page fetch to be (page_size). The library will then handle the task for you.
list eagerly fetches all records and returns them as a list, whereas stream returns an enumerator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the page method.
For more information about these methods, view the auto-generated library docs.
Handling Exceptions
If the Twilio API returns a 400 or a 500 level HTTP response, the twilio-ruby library will throw a Twilio::REST::RequestError. 400-level errors are normal during API operation (“Invalid number”, “Cannot deliver SMS to that number”, for example) and should be handled appropriately.
require 'twilio-ruby'
account_sid = "{{ account_sid }}" # Your Account SID from www.twilio.com/console
auth_token = "auth_token" # Your Auth Token from www.twilio.com/console
begin
@client = Twilio::REST::Client.new account_sid, auth_token
message = @client.messages.create(
body: "Hello from Ruby",
to: "+12345678901", # Replace with your phone number
from: "+12345678901") # Replace with your Twilio number
rescue Twilio::REST::TwilioError => e
puts e.message
end
More Documentation
If you'd like to learn more about how Twilio works, or for inspiration about what to build, try the Ruby quickstarts.
The Rest API Documentation has examples written in Ruby for every kind of action you could take with the Twilio API. You should start there if you know what you want to do with the Ruby library.
You may also want to refer to the open source twilio-ruby specific documentation for more details about the methods and classes contained in the gem.
Version 4.x of the Helper Library
The most recent version of the Ruby Helper Library is not API compatible with the previous 4.x version you may have used in previous Twilio applications. We encourage you to use the latest version possible. Refer to the Migration Guide if you find that you are using an older version.
Getting Help
Still running into problems?
- Report a problem with this tutorial, or contact our support team
- Report an issue with the twilio-ruby library on GitHub
- Submit a feature request for twilio-ruby on GitHub
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
