twilio-ruby 3.11.5 → 4.0.0

data/docs/usage/phone-numbers.rst

@@ -15,7 +15,7 @@ Searching and Buying a Number
 --------------------------------
 
 Finding numbers to buy couldn't be easier.
-We first search for a number in area code 530.
+We first search for a US number in area code 530.
 Once we find one, we'll purchase it for our account.
 
 .. code-block:: ruby
@@ -27,12 +27,13 @@ Once we find one, we'll purchase it for our account.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    numbers = @client.account.available_phone_numbers.list(:area_code=>"530")
+    numbers = @client.available_phone_numbers.get('US').list(area_code: "530")
 
-    if numbers:
-        numbers[0].purchase()
-    else:
-        print "No numbers in 530 available"
+    if numbers.any?
+      numbers[0].purchase()
+    else
+      puts "No numbers in 530 available"
+    end
 
 
 Local, Toll-Free, and Mobile Numbers
@@ -51,13 +52,13 @@ You can search for numbers for a given type.
 .. code-block:: ruby
 
     # local
-	numbers = @client.account.available_phone_numbers.local.list()
+    numbers = @client.available_phone_numbers.get('US').local.list()
 
     # toll free
-	numbers = @client.account.available_phone_numbers.toll_free.list()
+    numbers = @client.available_phone_numbers.get('US').toll_free.list()
 
     # mobile
-	numbers = @client.account.available_phone_numbers.mobile.list()
+    numbers = @client.available_phone_numbers.get('UK').mobile.list()
 
 Numbers Containing Words
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -67,26 +68,16 @@ The following example will find any phone number with "FOO" in it.
 
 .. code-block:: ruby
 
-	numbers = @client.account.available_phone_numbers.list(:contains=>"FOO")
+    numbers = @client.available_phone_numbers.get('US').list(contains: "FOO")
 
 You can use the ''*'' wildcard to match any character. The following example finds any phone number that matches the pattern ''D*D''.
 
 .. code-block:: ruby
 
-	numbers = @client.account.available_phone_numbers.list(:contains=>"D*D")
-
-
-International Numbers
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, the client library will look for US numbers. Set the
-:data:`country` keyword to a country code of your choice to search for
-international numbers.
-
-.. code-block:: ruby
-
-	numbers = @client.account.available_phone_numbers.list(:country=>"FR")
+    numbers = @client.available_phone_numbers.get('US').list(contains: "D*D")
 
+Other Number Searches
+^^^^^^^^^^^^^^^^^^^^^
 
 :meth:`PhoneNumbers.search` method has plenty of other options to augment your search :
 
@@ -100,6 +91,25 @@ The `AvailablePhoneNumbers REST Resource
 <http://www.twilio.com/docs/api/rest/available-phone-numbers>`_ documentation
 has more information on the various search options.
 
+Numbers Requiring Addresses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some phone numbers require you to have an address on file with Twilio to satisfy legal
+requirements before they can be purchased. By default, the client library will
+include numbers in the result lists regardless of their address requirements; you can
+filter these numbers out when searching for phone numbers to purchase.
+
+.. code-block:: ruby
+
+    # Exclude all numbers requiring addresses
+    numbers = @client.available_phone_numbers.get('AU').list(exclude_all_address_required: true)
+
+    # Exclude numbers requiring local addresses
+    numbers = @client.available_phone_numbers.get('AU').list(exclude_local_address_required: true)
+
+    # Exclude numbers requiring foreign addresses
+    numbers = @client.available_phone_numbers.get('AU').list(exclude_foreign_address_required: true)
+
 
 Buying a Number
 ---------------
@@ -115,7 +125,9 @@ If you've found a phone number you want, you can purchase the number.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @number = @client.account.phone_numbers.purchase({:phone_number => "+15305431234"})
+    @number = @client.available_phone_numbers.purchase(
+      phone_number: "+15305431234"
+    )
 
 However, it's easier to purchase numbers after finding them using search (as
 shown in the first example).
@@ -138,11 +150,13 @@ listed in the `IncomingPhoneNumbers Resource documentation
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.phone_numbers.list(api_version="2010-04-01").each do |number|
-        number.update({:voice_url => "http://twimlets.com/holdmusic?" + 
-            "Bucket=com.twilio.music.ambient", 
-            :status_callback => "http://example.com/callback"})
-
+    @client.available_phone_numbers.list.each do |number|
+      number.update(
+        voice_url: "http://twimlets.com/holdmusic?" \
+                   "Bucket=com.twilio.music.ambient",
+        status_callback: "http://example.com/callback"
+      )
+    end
 
 Changing Applications
 ----------------------
@@ -161,8 +175,8 @@ An :class:`Application` encapsulates all necessary URLs for use with phone numbe
 
     phone_sid = "PNXXXXXXXXXXXXXXXXX"
 
-    @number = @client.account.phone_numbers.get(phone_sid)
-    @number.update(:sms_application_sid => "APXXXXXXXXXXXXXXXXXX")
+    @number = @client.available_phone_numbers.get(phone_sid)
+    @number.update(sms_application_sid: "APXXXXXXXXXXXXXXXXXX")
 
 See :doc:`/usage/applications` for instructions on updating and maintaining Applications.
 

data/docs/usage/queues.rst

@@ -22,10 +22,10 @@ Listing Queues
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @queues = @client.account.queues.list()
-    
+    @queues = @client.queues.list
+
     @queues.each do |queue|
-        puts queue.sid
+      puts queue.sid
     end
 
 
@@ -44,10 +44,10 @@ represents all current calls in the queue.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @queue = @client.account.queues.get("QU123")
+    @queue = @client.queues.get("QU123")
 
     @queue.members.list().each do |member|
-        print member.call_sid
+      puts member.call_sid
     end
 
 
@@ -74,8 +74,8 @@ first call in the queue.
 
     queue_sid = "QUAAAAAAAAAAAAA"
     call_sid = "CAXXXXXXXXXXXXXX"
-    
-    @members = @client.account.queues.get(queue_sid).members
+
+    @members = @client.queues.get(queue_sid).members
 
     # Get the first call in the queue
     puts members.front.date_enqueued
@@ -106,7 +106,7 @@ default values are 'Front' and 'GET'
 
     queue_sid = "QUAAAAAAAAAAAAA"
 
-    @members = @client.account.queues.get(queue_sid).members
+    @members = @client.queues.get(queue_sid).members
 
     # Dequeue the first call in the queue
     puts @members.dequeue('http://www.twilio.com/welcome/call')

data/docs/usage/recordings.rst

@@ -14,7 +14,7 @@ Audio Formats
 
 Each :class:`Recording` has a few special methods. To get the url
 for the wav format of this recording, use :meth:`Recording.wav`. For the
-mp3 format, use :meth:`Recording.mp3`. To make requests for either of 
+mp3 format, use :meth:`Recording.mp3`. To make requests for either of
 these formats use the same method with a '!' appended. These methods
 both take a block to be executed as soon as the response returns.
 
@@ -35,11 +35,12 @@ for each :class:`Recording`.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @client.account.recordings.list().each do |recording|
-        puts recording.duration
+    @client.recordings.list().each do |recording|
+      puts recording.duration
+    end
 
 You can filter recordings by CallSid by passing the Sid as :attr:`call`.
-Filter recordings using :attr:`before` and :attr:`after` dates.
+Filter recordings using :attr:`DateCreated<` and :attr:`DateCreated>` dates.
 
 The following will only show recordings made before January 1, 2011.
 
@@ -52,9 +53,9 @@ The following will only show recordings made before January 1, 2011.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.recordings.list(before=date(2011,1,1)).each do |recording|:
-        puts recording.duration
-
+    @client.recordings.list('DateCreated<' => '2011-01-01').each do |recording|
+      puts recording.duration
+    end
 
 Deleting Recordings
 ---------------------
@@ -70,7 +71,7 @@ The :class:`Recordings` resource allows you to delete unnecessary recordings.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.recordings.get("RC123").delete()
+    @client.recordings.get("RC123").delete()
 
 
 Accessing Related Transcptions
@@ -89,8 +90,9 @@ with this recording.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @recording = @client.account.recordings.get("RC123")
+    @recording = @client.recordings.get("RC123")
 
     @recording.transcriptions.list().each do |transcription|
-        puts transcription.transcription_text
+      puts transcription.transcription_text
+    end
 

data/docs/usage/sip.rst

@@ -26,10 +26,10 @@ under sip.twilio.com.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @domain = @client.account.sip.domains.create(
-        {:friendly_name => "The Office Domain",
-         :voice_url => "http://example.com/voice",
-         :domain_name => "dunder-mifflin-scranton.sip.twilio.com",}
+    @domain = @client.sip.domains.create(
+      friendly_name: "The Office Domain",
+      voice_url: "http://example.com/voice"
+      domain_name: "dunder-mifflin-scranton.sip.twilio.com"
     )
     puts @domain.sid
 
@@ -38,7 +38,7 @@ Creating a new IpAccessControlList
 
 To control access to your new domain, you'll need to explicitly grant access
 to individual ip addresses. To do this, you'll first need to create an
-:class:`IpAccessControlList` to hold the ip addresses you wish to allow. 
+:class:`IpAccessControlList` to hold the ip addresses you wish to allow.
 
 .. code-block:: ruby
 
@@ -50,8 +50,8 @@ to individual ip addresses. To do this, you'll first need to create an
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @ip_acl = @client.account.sip.ip_access_control_lists.create(
-        {:friendly_name => "The Office IpAccessControlList",}
+    @ip_acl = @client.sip.ip_access_control_lists.create(
+      friendly_name: "The Office IpAccessControlList"
     )
     puts @ip_acl.sid
 
@@ -70,11 +70,11 @@ Now it's time to add an :class:`IpAddress` to your new :class:`IpAccessControlLi
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @ip_address = @client.account.sip.ip_access_control_lists.get(
-        "AL456",  # IpAccessControlList sid
+    @ip_address = @client.sip.ip_access_control_lists.get(
+      "AL456",  # IpAccessControlList sid
     ).ip_addresses.create(
-        {:friendly_name => "Dwights's Computer",
-         :ip_address => "192.168.1.42",}
+      friendly_name: "Dwights's Computer",
+      ip_address: "192.168.1.42"
     )
     puts @ip_address.sid
 
@@ -94,10 +94,11 @@ associate them. To do this, create an :class:`IpAccessControlListMapping`.
 
     @client = Twilio::REST::Client.new account_sid, auth_token
 
-    @ip_acl_mapping = @client.account.sip.domains.get(
-        "SD456",  # SIP Domain sid
+    @ip_acl_mapping = @client.sip.domains.get(
+      "SD456",  # SIP Domain sid
     ).ip_access_control_list_mappings.create(
-        {:ip_access_control_list_sid => "AL789"})
+      ip_access_control_list_sid: "AL789"
+    )
 
     puts @ip_acl_mapping.sid
 

data/docs/usage/taskrouter-tokens.rst

@@ -0,0 +1,98 @@
+.. module:: twilio.task_router
+
+============================
+TaskRouter Capability Tokens
+============================
+
+
+TaskRouter's Worker.js library lets you add `TaskRouter
+<https://www.twilio.com/docs/taskrouter>`_ Worker Activity controls
+and event notifications to your web applications. Worker.js uses a Websocket
+connection to TaskRouter to receive realtime notifications of Worker
+Reservations and Task details, and provides a simple API for modifying a
+Worker's current Activity.
+
+TaskRouter uses Twilio capability tokens to delegate scoped access to
+TaskRouter resources to your JavaScript application. Twilio capability tokens
+conform to the JSON Web Token (commonly referred to as a JWT and pronounced
+"jot") standard, which allow for limited-time use of credentials by a third
+party. Your web server needs to generate a Twilio capability token and provide
+it to your JavaScript application in order to register a TaskRouter worker.
+
+:class:`Capability` is responsible for the creation of these
+capability tokens. You'll need your Twilio AccountSid and AuthToken,
+the Sid of the Workspace you want to authorize access to, and the Sid
+of the Worker you're granting authorization for.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # Get these values from https://twilio.com/user/account
+    account_sid = "AC123"
+    auth_token = "secret"
+
+    # Create a Workspace and Worker in the TaskRouter account portal
+    # or through the TaskRouter API
+    worker_sid = "WK789"
+    worker_sid = "WK789"
+
+    @capability = Twilio::TaskRouter::Capability.new account_sid, auth_token, workspace_sid, worker_sid
+
+
+By default, the Capability object will allow the Worker.js process to
+read from and write to the websockets used to communicate events, and also
+to fetch the list of available activities in the workspace.
+
+There are three additional permissions you can grant using the Capability
+token, and in most cases you'll want to allow all of them for your application:
+
+
+Attribute Fetch
+===============
+
+This authorizes requests to retrieve the registered Worker's attributes from
+the TaskRouter API.
+
+.. code-block:: ruby
+
+    @capability.allow_worker_fetch_attributes
+
+
+Worker Activity Update
+======================
+
+This authorizes updates to the registered Worker's current Activity.
+
+.. code-block:: ruby
+
+    @capability.allow_worker_activity_updates
+
+
+Task Reservation Update
+=======================
+
+This authorizes updates to a Task's reservation status.
+
+.. code-block:: ruby
+
+    @capability.allow_task_reservation_updates
+
+
+Generate a Token
+================
+
+.. code-block:: ruby
+
+    token = @capability.generate_token
+
+By default, this token will expire in one hour. If you'd like to change the
+token expiration, :meth:`generate_token` takes an optional :attr:`ttl`
+argument.
+
+.. code-block:: ruby
+
+    token = @capability.generate_token(600)
+
+This token will now expire in 10 minutes. If you haven't guessed already,
+:attr:`ttl` is expressed in seconds.

data/docs/usage/taskrouter.rst

@@ -0,0 +1,226 @@
+.. module:: twilio.rest.resources.task_router
+
+==========
+TaskRouter
+==========
+
+Twilio TaskRouter is a system for distributing tasks such as phone calls,
+leads, support tickets, and other work items to the people and processes that
+can best handle them.
+
+For more information, see the `TaskRouter documentation
+<https://www.twilio.com/docs/taskrouter>_`.
+
+
+Creating a Workspace
+--------------------
+
+A Workspace is a container for your Tasks, Workers, TaskQueues, Workflows and
+Activities. Each of these items exists within a single Workspace and will not
+be shared across Workspaces.
+
+The following code will create a new :class:`Workspace` resource and print
+its unique ID.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+    # You can create a workspace through the portal, or put a fake value
+    # here to create your first workspace with the Ruby library
+    WORKSPACE_SID = "WSZZZZZZZZZ"
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    @workspace = @client.workspaces.create(
+        friendly_name: "Customer Support",
+        template: "FIFO",  # Sets up default activities and a FIFO TaskQueue
+    )
+    puts @workspace.sid
+
+
+Workflows
+---------
+
+Workflows control how tasks will be prioritized and routed into TaskQueues, and
+how Tasks should escalate in priority or move across queues over time.
+Workflows are described in a simple JSON format and can be modified through the
+REST API or through the account portal.
+
+The following code will create a new :class:`Workflow` resource and print its
+unique ID:
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    # See previous examples to create a Workspace
+    WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
+
+    # Some JSON to configure the Workflow. See the documentation at
+    # http://www.twilio.com/docs/taskrouter for more details.
+    CONFIG = <<-EOS
+    {
+       "task_routing":{
+          "filters":[
+             {
+                "friendly_name":"Gold Tickets",
+                "expression":"customer_value == 'Gold' AND type == 'ticket'",
+                "targets":[
+                   {
+                      "task_queue_sid":"WQ0123456789abcdef0123456789abcdef",
+                      "priority":"2"
+                   }
+                ]
+             }
+          ],
+          "default_filter":{
+             "task_queue_sid":"WQabcdef01234567890123456789abcdef"
+          }
+       }
+    }
+    EOS
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    @workspace = @client.workflows.create(
+        friendly_name: "Incoming Call Flow",
+        assignment_callback_url: "https://example.com/callback",
+        fallback_assignment_callback_url: "https://example.com/callback2",
+        configuration: CONFIG
+    )
+    puts @workspace.sid
+
+
+Activities
+----------
+
+Activities describe the current status of your Workers, which determines
+whether they are eligible to receive task assignments. Workers are always set
+to a single Activity.
+
+To create a new :class:`Activity`:
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    # See previous examples to create a Workspace
+    WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    @activity = @client.activities.create(
+        friendly_name: "Coffee Break",
+        available: false  # Whether workers are available to handle tasks during this activity
+    )
+    puts @activity.sid
+
+
+Workers
+-------
+
+Workers represent an entity that is able to perform tasks, such as an agent
+working in a call center, or a salesperson handling leads.
+
+To create a new :class:`Worker`:
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    # See previous examples to create a Workspace
+    WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    @worker = @client.workers.create(
+        friendly_name:"Jamie",
+        attributes:'{"phone": "+14155551234", "languages": ["EN", "ES"]}'
+    )
+    puts @worker.sid
+
+
+TaskQueues
+----------
+
+TaskQueues are the resource you use to categorize Tasks and describe which
+Workers are eligible to handle those Tasks. As your Workflows process Tasks,
+those Tasks will pass through one or more TaskQueues until the Task is assigned
+and accepted by an eligible Worker.
+
+To create a new :class:`TaskQueue`:
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    # See previous examples to create a Workspace
+    WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    @queue = @client.task_queues.create(
+        friendly_name: "Sales",
+        # The Activity to assign workers when a task is reserved for them
+        reservation_activity_sid: "WA11111111111",
+        # The Activity to assign workers when a task is assigned to them
+        assignment_activity_sid: "WA222222222222",
+    )
+    puts @queue.sid
+
+
+Tasks
+-----
+
+A Task instance resource represents a single item of work waiting to be
+processed.
+
+To create a new :class:`Task` via the REST API:
+
+.. code-block:: ruby
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    # See previous examples to create a Workspace
+    WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
+
+    @client = Twilio::REST::TaskRouterClient.new ACCOUNT_SID, AUTH_TOKEN, WORKSPACE_SID
+
+    # Some JSON containing attributes for this task. User-defined.
+    TASK_ATTRIBUTES = <<-EOS
+    {
+         "type": "call",
+         "contact": "+15558675309",
+         "customer-value": "gold",
+         "task-reason": "support",
+         "callSid": "CA42ed11..."
+    }
+    EOS
+
+    @task = @client.create(
+        attributes: TASK_ATTRIBUTES,
+        assignment_status: 'pending',
+    )
+    puts @task.sid

data/docs/usage/token-generation.rst

@@ -14,14 +14,14 @@ Twilio Client.
 Capability tokens are used by `Twilio Client
 <http://www.twilio.com/api/client>`_ to provide connection
 security and authorization. The `Capability Token documentation
-<http://www.twilio.com/docs/tokens>`_ explains in depth the purpose and
+<https://www.twilio.com/docs/client/capability-tokens>`_ explains in depth the purpose and
 features of these tokens.
 
-:class:`TwilioCapability` is responsible for the creation of these capability
-tokens. You'll need your Twilio AccountSid and AuthToken.
+:class:`Twilio::Util::Capability` is responsible for the creation of these
+capability tokens. You'll need your Twilio AccountSid and AuthToken.
 
 .. code-block:: ruby
-    
+
     require 'twilio-ruby'
 
     # Find these values at twilio.com/user/account
@@ -30,6 +30,21 @@ tokens. You'll need your Twilio AccountSid and AuthToken.
 
     @capability = Twilio::Util::Capability.new account_sid, auth_token
 
+You can also configure capability tokens 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
+
+    @capability = Twilio::Util::Capability.new
+
+
 
 Allow Incoming Connections
 ==============================

data/docs/usage/transcriptions.rst

@@ -26,6 +26,7 @@ The following code will print out the length of each :class:`Transcription`.
     auth_token = "YYYYYYYYYYYYYYYYYY"
 
     @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.account.transcriptions.list().each do |transcription|
-        puts transcription.duration
+    @client.transcriptions.list().each do |transcription|
+      puts transcription.duration
+    end