The Twilio Ruby Helper Library

Deprecation notice: New functionality will only be added to the new library (Ruby Helper Library 5.x). The old library (4.x) will be officially supported until 10/15/2017. After that day, Twilio will stop providing bug fixes and Support might ask you to upgrade before debugging issues. Learn how to migrate your existing application.

The twilio-ruby helper library lets you write Ruby code to make HTTP requests to the Twilio API. If you are interested in migrating to the newer 5.x version of the Twilio Ruby Helper Library from the 4.x version, check out this guide.

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

Try sending yourself an SMS message, like this:

require 'twilio-ruby'

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Your Account SID from www.twilio.com/console
auth_token = "your_auth_token"   # Your Auth Token from www.twilio.com/console

@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

puts message.sid

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'
auth_token = 'your_auth_token'

# 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',
  from: '+15017250604'
)

puts @call.sid

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

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

Accessing the 4.x Version 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. The older version will continue to work, and you will continue to find sample code for this version throughout our documentation. Should you need to install this version you can do so with the following command:

gem install twilio-ruby -v 4.13.0

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 browsing the Twilio tag on Stack Overflow.

Thanks for rating this page!

Need some help?