Learn more with Workshops and Technical Sessions


Developer Conference for Communications

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.

More Documentation

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.

If you'd like to learn more about how Twilio works, or for inspiration about what to build, try the Ruby quickstarts.

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.

And if you're interested in seeing documentation for the latest stable version of the API, refer to the open source twilio-ruby preview release documentation.

Installation

The easiest way to install twilio-ruby is from RubyGems. In the command line, run gem install twilio-ruby:

# Be sure to type "twilio-ruby", not just "twilio"
gem install twilio-ruby

Or, you can clone the source code for twilio-ruby, and install the library from there.

Installing the Edge Version

Edge

The "edge" version of the Twilio library will be used to introduce new behavior incompatible with the current stable API version. Successful features from edge will migrate to the next stable API version each time one is released. Unsuccessful features will be removed from the system.

In some cases you will want to install the bleeding-edge version of the API. The easiest way to install twilio-ruby edge version is by adding the gem to your Gemfile as so:

gem 'twilio-ruby', :git => 'https://github.com/twilio/twilio-ruby.git', :branch => 'edge'

Or, you can clone the edge branch for twilio-ruby, and install the library in your environemnt by running:

cd 'twilio-ruby/'
git checkout edge
gem build twilio-ruby.gemspec
# the gemname with version will print out from the following command
gem install twilio-ruby-{version}.edge.gem

Preview Release

The "preview release" version is a preview of a next generation helper library that is in an experimental state. We welcome and encourage your feedback.

gem 'twilio-ruby', :git => 'https://github.com/twilio/twilio-ruby.git', :branch => 'release-5.x'

Or, you can clone the edge branch for twilio-ruby, and install the library in your enviroment by running:

cd 'twilio-ruby/'
git checkout release-5.x
gem build twilio-ruby.gemspec
# the gemname with version will print out from the following command
gem install twilio-ruby-{version}.release-5.x.gem

"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

Try sending yourself an SMS message, like this:

send_sms.rb
require 'rubygems'
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'AC32a3c49700934481addd5ce1659f04d2'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

message = @client.account.messages.create(:body => "Jenny please?! I love you <3",
    :to => "+14159352345",     # Replace with your phone number
    :from => "+14158141829")   # Replace with your Twilio number
puts message.sid

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'

begin
    client = Twilio::REST::Client.new account_sid, auth_token
    client.account.messages.create(
      from => from_number,
      to =>   to_number,
      body => "Hello World"
    )
rescue Twilio::REST::RequestError => e
    puts e.message
end

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.

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'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

begin
    @client = Twilio::REST::Client.new account_sid, auth_token
    @client.account.messages.create({
        :from => '+1234567890',
        :to => '+1234567890',
        :body => 'Hello world'
    })
rescue Twilio::REST::RequestError => e
    puts e.message
end

Getting Help

Still running into problems?