twilio-ruby 3.11.5 → 4.0.0

data/docs/usage/accounts.rst

@@ -28,7 +28,7 @@ Right now the only valid attribute is :attr:`friendly_name`.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     @account = @client.accounts.get(account_sid)
-    @account.update({:friendly_name => "My Awesome Account"})
+    @account.update(friendly_name: "My Awesome Account")
 
 
 Creating Subaccounts
@@ -45,7 +45,7 @@ Subaccounts are easy to make.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @subaccount = @client.accounts.create({:name => "My Awesome SubAccount"})
+    @subaccount = @client.accounts.create(name: "My Awesome SubAccount")
 
 
 Managing Subaccounts
@@ -70,20 +70,20 @@ Client X hasn't paid you recently, so let's suspend their account.
 
 .. code-block:: ruby
 
-    @subaccount.update({:status => 'suspended'}
+    @subaccount.update(status: 'suspended')
 
 If it was just a misunderstanding, reenable their account.
 
 .. code-block:: ruby
 
-    @subaccount.update({:status => 'active'}
+    @subaccount.update(status: 'active')
 
 Otherwise, close their account permanently.
 
 .. code-block:: ruby
 
-    @subaccount.update({:status => 'closed'}
+    @subaccount.update(status: 'closed')
 
 .. warning::
-    This action can't be undone. 
+    This action can't be undone.
 

data/docs/usage/addresses.rst

@@ -0,0 +1,101 @@
+.. module:: twilio.rest.resources
+
+=========
+Addresses
+=========
+
+An Address instance resource represents your or your customer’s physical
+location within a country. Around the world, some local authorities require the
+name and address of the user to be on file with Twilio to purchase and own a
+phone number.
+
+For more information, see the `Address REST Resource
+<http://www.twilio.com/docs/api/rest/address`_ documentation.
+
+Creating an Address
+-------------------
+
+Addresses contain the name of your company or your customer’s company in
+addition to location information and an optional friendly name.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @address = @client.addresses.create(
+      friendly_name: "Homer",
+      customer_name: "Homer Simpson",
+      street: "742 Evergreen Terrace",
+      city: "Springfield",
+      region "IL",
+      postal_code: "62701",
+      iso_country: "US"
+    )
+
+Listing Addresses
+-----------------
+
+The following code will print out the :attr:`customer_name` for each :class:`Address`.
+
+.. code-block:: ruby
+
+    @addresses = @client.addresses.list()
+    @addresses.each do |address|
+      puts address.customer_name
+    end
+
+Filtering Addresses
+-------------------
+
+The list of Addresses can be filtered on :attr:`friendly_name`,
+:attr:`customer_name`, and/or :attr:`iso_country`.
+
+.. code-block:: ruby
+
+    @addresses = @client.addresses.list(iso_country: 'AU')
+    @addresses.each do |address|
+      puts address.customer_name
+    end
+
+Updating an Address
+-------------------
+
+All Address attributes other than :attr:`iso_country` can be updated.
+To create an Address with a different country, see the "Creating an Address" section.
+
+.. code-block:: ruby
+
+    @sid = 'AD123' # the address you'd like to update
+    @address = @client.addresses.get(@sid)
+    @address.update(customer_name: "Marge Simpson")
+
+Deleting an Address
+-------------------
+
+.. code-block:: ruby
+
+    address_sid = 'AD123'
+    @address = @client.addresses.get(address_sid)
+    @address.delete()
+
+Listing Dependent Phone Numbers
+-------------------------------
+
+Twilio will not permit you to delete an Address if it is the sole
+Address resource on your account that satisfies the address requirements
+for one or more of your purchased phone numbers.
+
+To see which phone numbers depend on a given address:
+
+.. code-block:: ruby
+
+    address_sid = 'AD123'
+    @address = @client.addresses.get(address_sid)
+    @address.dependent_phone_numbers.list.each do |number|
+      puts number.sid
+    end

data/docs/usage/applications.rst

@@ -26,8 +26,8 @@ The following code will print out the :attr:`friendly_name` for each :class:`App
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.applications.each do |app|
-        puts app.friendly_name
+    @client.applications.each do |app|
+      puts app.friendly_name
     end
 
 
@@ -45,8 +45,8 @@ You can filter applications by FriendlyName
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.applications.list({:friendly_name => 'FOO'})}.each do |app|
-        puts app.sid
+    @client.applications.list(friendly_name: 'FOO').each do |app|
+      puts app.sid
     end
 
 
@@ -66,8 +66,9 @@ accepts many other arguments for url configuration.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @application = @client.account.applications.create({:friendly_name => "My New App"})
-
+    @application = @client.applications.create(
+      friendly_name: "My New App"
+    )
 
 Updating an Application
 ------------------------
@@ -85,9 +86,8 @@ Updating an Application
     url = "http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient"
     app_sid = 'AP123' # the app you'd like to update
 
-    @application = @client.account.applications.get(app_sid)
-    @application.update({:voice_url => url})
-
+    @application = @client.applications.get(app_sid)
+    @application.update(voice_url: url)
 
 Deleting an Application
 -------------------------
@@ -103,6 +103,6 @@ Deleting an Application
     @client = Twilio::REST::Client.new account_sid, auth_token
 
     app_sid = 'AP123' # the app you'd like to delete
-    @client.account.applications.get(app_sid)
+    @client.applications.get(app_sid)
     @application.delete()
 

data/docs/usage/basics.rst

@@ -27,6 +27,19 @@ Once you have your credentials, you can create create a new :class:`Client` and
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
+You can also configure the client using the top level configure method, like so:
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    Twilio.configure do |config|
+      config.account_sid = "ACXXXXXXXXXXXXXXXXX"
+      config.auth_token = "YYYYYYYYYYYYYYYYYY"
+    end
+
+    @client = Twilio::REST::Client.new
+
 
 Listing Resources
 -------------------
@@ -43,7 +56,7 @@ The :class:`Client` gives you access to various list resources.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-	@calls = @client.account.calls.list()
+	@calls = @client.calls.list()
 
 :meth:`ListResource.list` accepts paging arguments.
 The following will return page 3 with page size of 25.
@@ -57,7 +70,7 @@ The following will return page 3 with page size of 25.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-	@calls = @client.account.calls.list(:page=>3, :page_size=>25)
+	@calls = @client.calls.list(page: 3, page_size: 25)
 
 
 Get an Individual Resource
@@ -76,7 +89,7 @@ Provide the :attr:`sid` of the resource you'd like to get.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @call = @client.account.calls.get("CA123")
+    @call = @client.calls.get("CA123")
     puts @call.to
 
 
@@ -97,6 +110,6 @@ and then call :meth:`delete` on it.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @recording = @client.account.recordings.get("RC123")
+    @recording = @client.recordings.get("RC123")
     @recording.delete()
 

data/docs/usage/caller-ids.rst

@@ -19,7 +19,9 @@ Validating a phone number is quick and easy.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @response = @client.account.outgoing_caller_ids.create(:phone_number => "+44 9876543212")
+    @response = @client.outgoing_caller_ids.create(
+      phone_number: "+44 9876543212"
+    )
     puts @response.validation_code
 
 Twilio will call the provided number and wait for the validation code to be
@@ -40,6 +42,6 @@ Deleting a phone number is quick and easy.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @response = @client.account.outgoing_caller_ids.list(:phone_number => "+15555555555")
+    @response = @client.outgoing_caller_ids.list(phone_number: "+15555555555")
     @callerid = response[0]
     @callerid.delete()

data/docs/usage/conferences.rst

@@ -20,10 +20,10 @@ Listing Conferences
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @conferences = @client.account.conferences.list()
+    @conferences = @client.conferences.list()
 
     @conferences.each do |conference|
-        puts conference.sid
+      puts conference.sid
     end
 
 
@@ -43,10 +43,10 @@ will return a list of all in-progress conferences and print their friendly name.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @conferences = @client.account.conferences.list({:status => "in-progress"})
-    
+    @conferences = @client.conferences.list(status: "in-progress")
+
     @conference.each do |conference|
-        puts conference.friendly_name
+      puts conference.friendly_name
     end
 
 
@@ -64,10 +64,10 @@ Each :class:`Conference` has a :attr:`participants` instance which represents al
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @conference = @client.account.conferences.get("CF123")
+    @conference = @client.conferences.get("CF123")
 
     @conference.participants.list.each.do |paricipant|
-        puts participant.sid
+      puts participant.sid
     end
 
 :class:`Conferences` and :class:`Participants` are subclasses of :class:`ListResource`.
@@ -94,15 +94,15 @@ code kicks out the first participant and mutes the rest.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @participants = @client.account.conferences.get("CF123").participants.list()
+    @participants = @client.conferences.get("CF123").participants.list()
 
-    if @participants.empty?
-        return
+    return if @participants.empty?
 
     # Kick the first person out
     @participants.pop().kick()
 
     # And mute the rest
     @participants.each do |participant|
-        participant.mute()
+      participant.mute()
+    end
 

data/docs/usage/errors.rst

@@ -18,12 +18,12 @@ handled appropriately.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     begin
-        @client = Twilio::REST::Client.new account_sid, auth_token
-        client.account.messages.create({
-            :from => '+1234567890',
-            :to => '+1234567890',
-            :body => 'Hello world'
-        })
+      @client = Twilio::REST::Client.new account_sid, auth_token
+      client.messages.create({
+        from: '+1234567890',
+        to: '+1234567890',
+        body: 'Hello world'
+      })
     rescue Twilio::REST::RequestError => e
-        puts e.message
+      puts e.message
     end

data/docs/usage/messages.rst

@@ -24,9 +24,11 @@ Send a text message in only a few lines of code.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @message = @client.account.messages.create({:to => "+13216851234",
-                                       :from => "+15555555555",
-                                       :body => "Hello!"})
+    @message = @client.messages.create(
+      to: "+13216851234",
+      from: "+15555555555",
+      body: "Hello!"
+    )
 
 If you want to send a message from a `short code
 <http://www.twilio.com/api/sms/short-codes>`_ on Twilio, just set :attr:`from`
@@ -48,24 +50,27 @@ To send a picture, set :attr:`media_url` to the url of the picture you wish to s
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @message = @client.account.messages.create({:to => "+15558676309",
-                                       :from => "+15555555555",
-                                       :body => "Jenny I need you!",
-                                       :media_url => "http://twilio.com/heart.jpg"})
+    @message = @client.messages.create(
+      to: "+15558676309",
+      from: "+15555555555",
+      body: "Jenny I need you!",
+      media_url: "http://twilio.com/heart.jpg"
+    )
 
 You can send multiple pictures in the same message by setting :attr:`media_url` to
 an array of urls.
 
 .. code-block:: ruby
 
-    @message = @client.account.messages.create({:to => "+15558676309",
-                                       :from => "+15555555555",
-                                       :body => "Jenny I need you!",
-                                       :media_url => [
-                                            "http://twilio.com/heart.jpg",
-                                            "http://twilio.com/rose.jpg"
-                                        ]})
-
+    @message = @client.messages.create(
+      to: "+15558676309",
+      from: "+15555555555",
+      body: "Jenny I need you!",
+      media_url: [
+        "http://twilio.com/heart.jpg",
+        "http://twilio.com/rose.jpg"
+      ]
+    )
 
 Retrieving Sent Messages
 -------------------------
@@ -80,9 +85,29 @@ Retrieving Sent Messages
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @client.account.messages.list.each do |message|
-        puts message.body
+    @client.messages.list.each do |message|
+      puts message.body
+    end
+
+Redacting or Deleting Messages
+------------------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @msg_sid = 'MM123'
+    @msg = @client.messages.get('MM123')
+    # Deletes the Body field contents
+    @msg.redact
 
+    # Removes the entire Message record
+    @msg.delete
 
 Filtering Your Messages
 -------------------------
@@ -101,9 +126,12 @@ The following will only show messages to "+5466758723" on January 1st, 2011.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @messages = @client.account.messages.list({:to => "+5466758723", :date_sent => "2011-01-01"})
+    @messages = @client.messages.list(
+      to: "+5466758723",
+      date_sent: "2011-01-01"
+    )
 
     @messages.each do |message|
-        puts message.body
-    
+      puts message.body
+    end
 

data/docs/usage/notifications.rst

@@ -24,8 +24,9 @@ current :class:`Notification` resources.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @client.account.notifications.list().each do |notification|:
-        puts notification.more_info
+    @client.notifications.list.each do |notification|
+      puts notification.more_info
+    end
 
 You can filter transcriptions by :attr:`log` and :attr:`message_date`.
 The :attr:`log` value is 0 for `ERROR` and 1 for `WARNING`.
@@ -42,8 +43,9 @@ The :attr:`log` value is 0 for `ERROR` and 1 for `WARNING`.
 
     ERROR = 0
 
-    @client.account.notifications.list(log=ERROR).each do |notification|:
-        puts notification.error_code
+    @client.notifications.list(log=ERROR).each do |notification|
+      puts notification.error_code
+    end
 
 .. note:: Due to the potentially voluminous amount of data in a notification,
     the full HTTP request and response data is only returned in the

data/docs/usage/phone-calls.rst

@@ -25,9 +25,11 @@ outputs valid `TwiML <http://www.twilio.com/docs/api/twiml/>`_.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @call = @client.account.calls.create({:to => "9991231234",
-                                  :from => "9991231234",
-                                  :url => "http://foo.com/call.xml"})
+    @call = @client.calls.create(
+      to: "9991231234",
+      from: "9991231234",
+      url: "http://foo.com/call.xml"
+    )
     puts @call.length
     puts @call.sid
 
@@ -48,8 +50,25 @@ you can use the client to retrieve that record.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     sid = "CA12341234"
-    @call = @client.account.calls.get(sid)
+    @call = @client.calls.get(sid)
 
+Delete a Call Record
+--------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    sid = "CA12341234"
+    @call = @client.calls.get(sid)
+
+    # Removes the entire record from Twilio's storage
+    @call.delete
 
 Accessing Specific Call Resources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -69,7 +88,7 @@ just like the :class:`Calls` resource itself.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     sid = "CA12341234"
-    @call = @client.account.calls.get(sid)
+    @call = @client.calls.get(sid)
 
     puts @call.notifications.list()
     puts @call.recordings.list()
@@ -89,9 +108,9 @@ However, what if you only have a `CallSid`, and not the actual
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     sid = "CA24234"
-    puts @client.notifications.list({:call => sid})
-    puts @client.recordings.list({:call => sid})
-    puts @client.transcriptions.list({:call => sid})
+    puts @client.notifications.list(call: sid)
+    puts @client.recordings.list(call: sid)
+    puts @client.transcriptions.list(call: sid)
 
 
 Modifying Live Calls
@@ -109,10 +128,10 @@ redirect them as necessary
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @calls = @client.account.calls.list({:status => "in-progress"})
+    @calls = @client.calls.list(status: "in-progress")
 
     @calls.each do |call|
-        call.redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
+      call.redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
     end
 
 
@@ -127,10 +146,10 @@ Ending all live calls is also possible
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @calls = @client.account.calls.list({:status => "in-progress"})
+    @calls = @client.calls.list(status: "in-progress")
 
     @calls.each do |call|
-        call.hangup()
+      call.hangup()
     end
 
 Note that :meth:`hangup` will also cancel calls currently queued.
@@ -148,7 +167,7 @@ resource to update the record without having to use :meth:`get` first.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     sid = "CA12341234"
-    @client.account.calls.get(sid).redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
+    @client.calls.get(sid).redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
 
 Hanging up the call also works.
 
@@ -162,5 +181,5 @@ Hanging up the call also works.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
     sid = "CA12341234"
-    @client.account.calls.get(sid).hangup()
+    @client.calls.get(sid).hangup()