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.api.v2010.calls
@participants = @client.api.v2010.conferences('a_conference_sid').participants

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 methods such as #list and #stream

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.

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

#stream is similar to #list but lazily loads records until the limit is reached.

Instance Resource Objects

Instance resource objects represent instance resources in the Twilio REST API. They support the methods such as #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.api.incoming_phone_numbers
@number = @incoming_numbers('PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
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('PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
@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.api.outgoing_caller_ids
d@caller_ids('PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').delete