The documentation for the Twilio API can be found here.
The individual releases here.
Supported Ruby Versions
This library supports the following Ruby implementations:
- Ruby 2.4
- Ruby 2.5
- Ruby 2.6
- Ruby 2.7
- Ruby 3.0
- Ruby 3.1
Migrating from 5.x
To install using Bundler grab the latest stable version:
gem 'twilio-ruby', '~> 6.7.0'
To manually install
twilio-ruby via Rubygems simply gem install:
gem install twilio-ruby -v 6.7.0
To build and install the development branch yourself from the latest source:
git clone gi[email protected]:twilio/twilio-ruby.git cd twilio-ruby make install
Info If the command line gives you an error message that says Permission Denied, try running the above commands with sudo.
sudo gem install twilio-ruby
Test your installation
To make sure the installation was successful, try sending yourself an SMS message, like this:
require "twilio-ruby" # Your Account SID and Auth Token from console.twilio.com account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" auth_token = "your_auth_token" @client = Twilio::REST::Client.new account_sid, auth_token message = @client.messages.create( body: "Hello from Ruby", to: "+12345678901", # Text this number from: "+15005550006", # From a valid Twilio number ) puts message.sid
Warning 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.
Authenticate the Client
require 'twilio-ruby' # Your Account SID and Auth Token from console.twilio.com account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # Initialize the Twilio Client with your credentials @client = ::::. account_sid, auth_token
Use An API Key
require 'twilio-ruby' # Your Account SID from console.twilio.com account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' # API Key from twilio.com/console/project/api-keys api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz' api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up a client to talk to the Twilio REST API using an API Key @client = ::::. api_key_sid, api_key_secret, account_sid
Specify a Region and/or Edge
To take advantage of Twilio's Global Infrastructure, specify the target Region and/or Edge for the client:
# set up a client to talk to the Twilio REST API over a specific region and edge @client = ::::. account_sid, auth_token, nil, 'au1' @client.edge = 'sydney' # you may also specify the region and/or edge after client creation @client = ::::. account_sid, auth_token @client.region = 'au1' @client.edge = 'sydney'
This will result in the
hostname transforming from
Make a Call
@client.calls.create( from: '+14159341234', to: '+16105557069', url: 'http://example.com' )
Send an SMS
@client..create( from: '+14159341234', to: '+16105557069', body: 'Hey there!' )
List your SMS Messages
Fetch a single SMS message by Sid
# put the message sid you want to retrieve here: = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' @client.().fetch
Iterate through records
The library automatically handles paging for you. Collections, such as
list and stream methods that page under the hood. With both
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
For more information about these methods, view the auto-generated library docs.
require 'twilio-ruby' account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' auth_token = 'your_auth_token' @client = Twilio::REST::Client.new(account_sid, auth_token) @client.calls.list .each do |call| puts call.direction end
Enable Debug logging
In order to enable debug logging, pass in a 'logger' instance to the client with the level set to at least 'DEBUG'
@client = ::::. account_sid, auth_token myLogger = Logger.new(STDOUT) myLogger.level = Logger::DEBUG @client.logger = myLogger @client = ::::. account_sid, auth_token myLogger = Logger.new('my_log.log') myLogger.level = Logger::DEBUG @client.logger = myLogger
Handle Exceptions #exceptions
If the Twilio API returns a 400 or a 500 level HTTP response, the
library will throw a
Twilio::REST::RestError. 400-level errors are normal
during API operation (
“Cannot deliver SMS to that number”,
for example) and should be handled appropriately.
require 'twilio-ruby' account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' auth_token = 'your_auth_token' @client = Twilio::REST::Client.new account_sid, auth_token begin messages = @client.messages.list(limit: 20) rescue Twilio::REST::RestError => e puts e.message end
Debug API requests
To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.
For example, you can retrieve the status code of the last response like so:
require 'rubygems' # Not necessary with ruby 1.9 but included for completeness require 'twilio-ruby' # Your Account SID and Auth Token from console.twilio.com account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' auth_token = 'your_auth_token' @client = ::::.(account_sid, auth_token) @message = @client..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
Customize 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
To use a custom HTTP client with this helper library, please see the advanced example of how to do so.
To apply customizations such as middleware, you can use the
configure_connection method like so:
@client.http_client.configure_connection do |faraday| faraday.use SomeMiddleware end
Get started With Client Capability Tokens
If you just need to generate a Capability Token for use with Twilio Client, you can do this:
require 'twilio-ruby' # put your own account credentials here: account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up capability = ::::. account_sid, auth_token # allow outgoing calls to an application outgoing_scope = ::::::. 'AP11111111111111111111111111111111' capability.add_scope(outgoing_scope) # allow incoming calls to 'andrew' incoming_scope = ::::::. 'andrew' capability.add_scope(incoming_scope) # generate the token string @token = capability.to_s
There is a slightly more detailed document in the Capability section of the wiki.
To control phone calls, your application needs to output TwiML.
You can construct a TwiML response like this:
require 'twilio-ruby' response = ::::. do |r| r.say(message: 'hello there', voice: 'alice') r.dial(caller_id: '+14159992222') do |d| d.client 'jenny' end end # print the result puts response.to_s
This will print the following (except for the whitespace):
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say voice="alice">hello there</Say> <Dial callerId="+14159992222"> <Client>jenny</Client> </Dial> </Response>
Dockerfile present in this repository and its respective
twilio/twilio-ruby Docker image are currently used by Twilio for testing purposes only.
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!