Gem Version Build Status Code Quality


A module for using the Twilio REST API and generating valid TwiML. Click here to read the full documentation.


To install using Bundler grab the latest stable version:

gem 'twilio-ruby', '~> 5.0.0.rc1'

To manually install twilio-ruby via Rubygems simply gem install:

gem install twilio-ruby -v 5.0.0.rc1

To build and install the development branch yourself from the latest source:

git clone
cd twilio-ruby
make install

Migration from 4.x

Upgrade Guide




During the Release Candidate period of this library, please leave all feedback and issues in the Github Issues for twilio-ruby.

Getting Started

Setup Work

require 'twilio-ruby'

# put your own credentials here
 = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# set up a client to talk to the Twilio REST API
@client = , auth_token

# alternatively, you can preconfigure the client like so
Twilio.configure do |config|
  config. = 
  config.auth_token = auth_token

# and then you can create a new client without parameters
@client =

Make a Call

  from: '+14159341234',
  to: '+16105557069',
  url: ''

Send an SMS

  from: '+14159341234',
  to: '+16105557069',
  body: 'Hey there!'

Customizing your HTTP Client

twilio-ruby uses Faraday to make HTTP requests. You can tell Twilio::REST::Client to use any of the Faraday adapters like so:

@client.http_client.adapter = :typhoeus

Getting Started With Client Capability Tokens

If you just need to generate a Capability Token for use with Twilio Client, you can do this:

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

# put your own account credentials here:
 = 'AC043dcf9844e13758bc3a36a84c29761'
auth_token = '62ea81de3a5b413254eb263595357c69'

# set up
capability = , auth_token

# allow outgoing calls to an application
capability.allow_client_outgoing 'AP89a0180a1a4ddf1da954efca349b7a20'

# allow incoming calls to 'andrew'
capability.allow_client_incoming 'andrew'

# generate the token string
@token = capability.generate

There is a slightly more detailed document in the Capability section of the wiki.

Getting Started With TwiML

TwiML support is based on the Builder library. You can construct a TwiML response like this:

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

# build up a response
response = do |r|
  r.Say 'hello there', voice: 'alice'
  r.Dial callerId: '+14159992222' do |d|
    d.Client 'jenny'

# print the result
puts response.text

This will print the following (except for the whitespace):

<?xml version="1.0" encoding="UTF-8"?>
  <Say voice="alice">hello there</Say>
  <Dial callerId="+14159992222">

Supported Ruby Versions

This library supports and is tested against the following Ruby implementations:

Getting help

If you need help installing or using the library, please contact Twilio Support at first. Twilio's Support staff are well-versed in all of the Twilio Helper Libraries, and usually reply within 24 hours.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!