Twilio.rb

Interact with the Twilio API in a nice Ruby way

Installation

The library has been packaged as a gem and is available from rubygems.org

gem install twilio-rb

Usage

Require the library in your script as

require 'twilio'

Configuration

Configuration for this library is encapsulated within Twilio::Config. One needs to setup with an Account SID and an Auth Token, e.g.

# This should be in an initializer or similar
Twilio::Config.setup do
  account_sid   'AC0000000000000000000000000000'
  auth_token    '000000000000000000000000000000'
end

Any method that calls the Twilio API will raise Twilio::ConfigurationError if either Account SID or Auth Token are not configured.

The Account object

The Twilio API in its current incarnation supports one Twilio account per Account SID, and so the Twilio::Account object correspondingly is a singleton object.

To access properties of the account the property name should be called as a method on the object itself, e.g.

Twilio::Account.friendly_name

The first time a method is invoked on the object an API call is made to retrieve the data. The methods themselves are not defined until they are called, i.e. lazy evaluation. This strategy means that addtional properties added to subsequent versions of the API should not break the library.

To reload the data when needed Twilio::Account.reload! will make another API call and update its own internal state.

Predicate methods i.e. those ending in ? map directly to the status of the account, e.g. Twilio::Account.suspended? returns true if Twilio have suspended your account. Again, all of these methods are defined on the fly.

The only account property that can be modified via the REST API is the friendly name, e.g.

Twilio::Account.friendly_name = "I'm so vain, I had to change my name!"

This will update the API immediately with a PUT request.

Please refer to the Twilio REST API documentation for an up to date list of properties.

Making a telephone call

The API used to make a telephone call is similar to interacting with an ActiveRecord model object.

Twilio::Call.create :to => '+16465551234', :from => '+19175550000', 
                    :url => "http://example.com/call_handler"

or

call = Twilio::Call.new :to => '+16465551234', :from => '+19175550000', 
                        :url => "http://example.com/call_handler"

call.save

The parameter keys should be given as underscored symbols. They will be converted internally to camelized strings prior to an API call being made.

Please see the Twilio REST API documentation for an up to date list of supported parameters.

Modifying a live telephone call

Once a call has been been created it can be modified with the following methods:

Twilio::Call#cancel! will terminate the call if its state is queued or ringing Twilio::Call#complete! will terminate the call even if its state is in-progress Twilio::Call#url= will immediately redirect the call to a new handler URL

Twilio::Call#cancel! and Twilio::Call#complete! will raise Twilio::InvalidStateError if the call has not been "saved". Twilio::Call#url= will updated its state with the new URL ready for when Twilio::Call#save is called.

Sending an SMS message

The API used to send an SMS message is similar to interacting with an ActiveRecord model object.

Twilio::SMS.create :to => '+16465551234', :from => '+19175550000', 
                   :body => "Hey baby, how was your day? x"

or

sms = Twilio::SMS.new :to => '+16465551234', :from => '+19175550000', 
                      :body => "Hey baby, how was your day? x"

sms.save

The parameter keys should be given as underscored symbols. They will be converted internally to camelized strings prior to an API call being made.

Please see the Twilio REST API documentation for an up to date list of supported parameters.

Building TwiML documents

A TwiML document is an XML document. The best way to build XML in Ruby is with Builder, and so it follows that we should use builder for TwiML. Twilio::TwiML.build behaves like builder except element names are capitalised for you and attributes are camelized for you as well. This is so you may continue to write beautiful code.

The following Ruby code:

Twilio::TwiML.build do |res| 
  res.say    'Hey man! Listen to this!', :voice => 'man'
  res.play   'http://foo.com/cowbell.mp3'
  res.say    'What did you think of that?!', :voice => 'man'
  res.record :action => "http://foo.com/handleRecording.php",
             :method => "GET", :max_length => "20",
             :finish_on_Key => "*"
  res.gather :action => "/process_gather.php", :method => "GET" do |g|
    g.say 'Now hit some buttons!'
  end
  res.say    'Awesome! Thanks!', :voice => 'man'
  res.hangup
end

Therefore emits the following TwiML document:

<Response>
  <Say voice="man">Hey man! Listen to this!</Say>
  <Play>http://foo.com/cowbell.mp3</Play>
  <Say voice="man">What did you think of that?!</Say>
  <Record maxLength="20" method="GET" action="http://foo.com/handleRecording.php" finishOnKey="*"/>
  <Gather method="GET" action="/process_gather.php">
    <Say>Now hit some buttons!</Say>
  </Gather>
  <Say voice="man">Awesome! Thanks!</Say>
  <Hangup/>
</Response>

This specialised behaviour only affects Twilio::TwiML.build and does not affect Builder in general.