twilio-ruby¶ ↑
The default branch name for this repository has been changed to main
as of 07/27/2020.
Documentation¶ ↑
The documentation for the Twilio
API can be found here.
The Ruby library documentation can be found here and individual releases here.
Versions¶ ↑
twilio-ruby
uses a modified version of Semantic Versioning for all changes. See this document for details.
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
Migrating from 4.x¶ ↑
Installation¶ ↑
To install using Bundler grab the latest stable version:
gem 'twilio-ruby', '~> 5.58.2'
To manually install twilio-ruby
via Rubygems simply gem install:
gem install twilio-ruby -v 5.58.2
To build and install the development branch yourself from the latest source:
git clone git@github.com:twilio/twilio-ruby.git cd twilio-ruby make install
Getting Started¶ ↑
Setup Work¶ ↑
require 'twilio-ruby' # put your own credentials here account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up a client to talk to the Twilio REST API @client = Twilio::REST::Client.new account_sid, auth_token
Use An API Key¶ ↑
require 'twilio-ruby' # put your own credentials here account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz' api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up a client to talk to the Twilio REST API using an API Key @client = Twilio::REST::Client.new 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 = Twilio::REST::Client.new account_sid, auth_token, nil, 'au1' @client.edge = 'sydney' # you may also specify the region and/or edge after client creation @client = Twilio::REST::Client.new account_sid, auth_token @client.region = 'au1' @client.edge = 'sydney'
This will result in the hostname
transforming from api.twilio.com
to api.sydney.au1.twilio.com
.
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 = Twilio::REST::Client.new account_sid, auth_token myLogger = Logger.new(STDOUT) myLogger.level = Logger::DEBUG @client.logger = myLogger @client = Twilio::REST::Client.new account_sid, auth_token myLogger = Logger.new('my_log.log') myLogger.level = Logger::DEBUG @client.logger = myLogger
Make a Call¶ ↑
@client.calls.create( from: '+14159341234', to: '+16105557069', url: 'http://example.com' )
Send an SMS¶ ↑
@client.messages.create( from: '+14159341234', to: '+16105557069', body: 'Hey there!' )
List your SMS Messages¶ ↑
@client.messages.list(limit: 20)
Fetch a single SMS message by Sid¶ ↑
# put the message sid you want to retrieve here: message_sid = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' @client.messages(message_sid).fetch
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
To use a custom HTTP client with this helper library, please see the Twilio documentation.
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
Handling Errors¶ ↑
begin messages = @client.messages.list(limit: 20) rescue Twilio::REST::RestError => e puts e.message end
For more descriptive exception types, please see the Twilio documentation.
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 'twilio-ruby' # put your own account credentials here: account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up capability = Twilio::JWT::ClientCapability.new account_sid, auth_token # allow outgoing calls to an application outgoing_scope = Twilio::JWT::ClientCapability::OutgoingClientScope.new 'AP11111111111111111111111111111111' capability.add_scope(outgoing_scope) # allow incoming calls to 'andrew' incoming_scope = Twilio::JWT::ClientCapability::IncomingClientScope.new '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.
Generating TwiML¶ ↑
To control phone calls, your application needs to output TwiML.
You can construct a TwiML response like this:
require 'twilio-ruby' response = Twilio::TwiML::VoiceResponse.new 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>
Docker Image¶ ↑
The Dockerfile
present in this repository and its respective twilio/twilio-ruby
Docker image are currently used by Twilio
for testing purposes only.
Getting help¶ ↑
If you need help installing or using the library, please check the Twilio Support Help Center first, and file a support ticket if you don't find an answer to your question.
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!