muthhus / twilio-ruby

A Ruby gem for communicating with the Twilio API and generating TwiML

twilio-ruby

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

Installation

To install using Bundler grab the latest stable version:

gem 'twilio-ruby', '~> 3.12'

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

gem install twilio-ruby

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

git clone [email protected]:twilio/twilio-ruby.git
cd twilio-ruby
make install

Getting Started With REST

Setup Work

require 'rubygems' # not necessary with ruby 1.9 but included for completeness
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

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

# and then you can create a new client without parameters
@client = Twilio::REST::Client.new

Send an SMS

@client.messages.create(
  from: '[phone]',
  to: '[phone]',
  body: 'Hey there!'
)

Send an MMS

@client.messages.create(
  from: '[phone]',
  to: '[phone]',
  body: 'Hey there!',
  media_url: 'http://example.com/smileyface.jpg'
)

Do Some Stuff With Calls

# make a new outgoing call
@call = @client.calls.create(
  from: '[phone]',
  to: '[phone]',
  url: 'http://example.com/call-handler'
)

# hangup a ringing call, but don't touch it if it's connected
@call.cancel

# if you have the call sid, you can fetch a call object via:
@call = @client.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662')

# redirect an in-progress call
@call.redirect_to('http://example.com/call-redirect')

# hangup a call, no matter whether it is ringing or connected
@call.hangup

List Calls after a certain time

# list calls made or received on or after May 13, 2013
@client.calls.list("start_time>" => "2013-05-13") # Notice we omit the "=" in the "start_time>=" parameter because it is automatically added

Buy a Phone Number

# print some available numbers
@numbers = @client.available_phone_numbers.get('US').local.list(
  contains: 'AWESOME'
)
@numbers.each {|num| puts num.phone_number}

# buy the first one
@number = @numbers[0].phone_number
@client.incoming_phone_numbers.create(phone_number: @number)

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:
account_sid = 'AC043dcf9844e13758bc3a36a84c29761'
auth_token = '62ea81de3a5b413254eb263595357c69'

# set up
capability = Twilio::Util::Capability.new account_sid, 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 = Twilio::TwiML::Response.new do |r|
  r.Say 'hello there', voice: 'alice'
  r.Dial callerId: '[phone]' do |d|
    d.Client 'jenny'
  end
end

# print the result
puts response.text

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="[phone]">
    <Client>jenny</Client>
  </Dial>
</Response>

Supported Ruby Versions

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

• Ruby 2.1.0
• Ruby 2.0.0
• Ruby 1.9.3
• JRuby
• Rubinius

More Information

There are more detailed examples in the included examples directory. Also for thoose upgrading, the upgrade guide is available in the twilio-ruby github wiki.