REST

Documentation: REST

The twilio-ruby REST API implementation is based on a couple of simple primitives. At the base there is a Client object that you instantiate with your account credentials. With an instance of this object you can access all of the resources within the Twilio REST API.

You instantiate a client object like this:

@client = Twilio::REST::Client.new 'your_account_sid', 'your_auth_token'

There are a few other options with which you can instantiate your Twilio REST Client, including an HTTP proxy domain and port. See the Client class for the full definition.

Every list resource and instance resource in the Twilio REST API is mapped to an object on the Client instance. These objects are nested the same way they are in the actual Twilio REST API. For example, the following urls:

/2010-04-01/Accounts/{your_account_sid}/Calls
/2010-04-01/Accounts/{your_account_sid}/Conferences/{conference_sid}/Participants

are mapped to the following twilio-ruby objects:

@calls = @client.accounts.get('your_account_sid').calls
@participants = @client.accounts.get('your_account_sid').conferences.get('a_conference_sid').participants

As you can probably see already, grabbing a handle to your account is a pretty common need. So there's a shortcut:

# the following are both handles to your account
@client.accounts.get('your_account_sid') # the long way
@client.account # the shortcut

There are only really two types of objects within twilio-ruby: list resource objects and instance resource objects.

List Resource Objects

List resource objects represent list resources in the Twilio REST API, such as Calls and IncomingPhoneNumbers. They support three methods: #list, #get and #create.

The #list method lets you fetch a list of instance resource objects. It supports the same parameters and filters as the Twilio REST API for each list resource object. You pass these arguments as a hash to the #list method like this:

# return a list of calls made from 415.935.5555
@calls.list(:from => '+14159355555')

The #get method returns a single instance resource object based on its sid or other unique id:

@call = @calls.get('CAe1644a7eed5088b159577c5802d8be38')

The #create method creates a new instance resource object within Twilio. Just like #list, #create takes a hash of parameters to send to Twilio when creating the resource. Refer to the Twilio REST documentation for each resource type to determine which options to pass. Here is an example using calls:

params = {
  :from => 'a_twilio_number',
  :to => 'a_different_number',
  :url => 'http://yourapp.com/handle_call'
}
@new_call = @calls.create(params)

Instance Resource Objects

Instance resource objects represent instance resources in the Twilio REST API. They support the methods #update and #delete, although not every instance resource is updatable or deletable. Refer to the Twilio REST API documentation for the resource type you are interested in to see whether it is possible to update or delete it.

Instance resource objects also have all the properties that the Twilio REST API returns. So for example, to print the VoiceUrl for a particular IncomingPhoneNumber object:

@incoming_numbers = @client.account.incoming_phone_numbers
@number = @incoming_numbers.get('PNe2d8e63b37f46f2adb16f228afdb9058')
print @number.voice_url

The #update method allows you to update the properties of an instance resource. For instance, to update the VoiceUrl and SmsUrl properties on an IncomingPhoneNumber resource you would do something like the following:

@number = @incoming_numbers.get('PNe2d8e63b37f46f2adb16f228afdb9058')
@number.update(
  :voice_url => 'http://yourapp.com/new_call_handler',
  :sms_url => 'http://yourapp.com/new_sms_handler'
)

The #delete method deletes an instance resource from Twilio. Use this method carefully since most deletes are unrecoverable. Here's an example of using #delete to delete one of your account's OutgoingCallerIds:

@caller_ids = @client.account.outgoing_caller_ids
@caller_ids.get('PN6f2adb16f228afdb9058e2d8e63b37f4').delete