twilio-ruby 3.15.1 → 3.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fbf01b84361cd43929e39a6edee180274f39e52a
-  data.tar.gz: c88951b668570f7c2cf9eb5bce608917366357ea
+  metadata.gz: 55ea3eb8f942cafe675c70aad8fa1ff5bf3836bf
+  data.tar.gz: b2dfc49ca27752b0e6bc87f8e7c5fc9095251627
 SHA512:
-  metadata.gz: 24a085c8ac996ba2b85848babda9246f5bffcdd378e73122884efbfc6dfa3506cd4cb47bb42bb3bb9a1d9cfa990e7b30c9a2e2b913da2b0bde9094fdd112d47c
-  data.tar.gz: 6495299185882caa6eeb2797b2f12863c1bc9e4d64aa24a643107ecf80d0b93627831d41f9d867a755ee9c1d68d96db7938cd9bc62f89578fde617456ca42efd
+  metadata.gz: 7df8d0e86f338607a6696a0defeda6283a5055870feccf48f15f47754a92e7e32a42961d9c7acdce974595511e1f1831034251f27aadfd0514eb41daea0b6489
+  data.tar.gz: a9e7eeea7956069958f186b2c62811283680db576cb0479b1b835c31826a94804f9aa1ce622d42661ef73a30f9c980b3e390dfbbe98f88f597b2c215c0c52fe1

data/CHANGES.md

@@ -1,6 +1,13 @@
 twilio-ruby changelog
 =====================
 
+Version 3.15.2
+--------------
+
+Released March 10, 2015
+
+- Add missing documentation on TaskRouter client
+
 Version 3.15.1
 --------------
 

data/LICENSE.md

@@ -1,5 +1,7 @@
 Copyright (c) 2010-2014 Andrew Benton.
 
+The MIT License (MIT)
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
@@ -16,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/docs/index.rst

@@ -55,6 +55,21 @@ Query the Twilio REST API to create phone calls, send SMS/MMS messages and more!
     usage/queues
     usage/sip
 
+
+TaskRouter
+---------
+
+Query the Twilio TaskRouter API to set up workspaces and task routing, and
+create capability tokens to authorize your client-side code to safely update
+state.
+
+.. toctree::
+    :maxdepth: 1
+
+    usage/taskrouter
+    usage/taskrouter-tokens
+
+
 TwiML
 ---------
 

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/lib/twilio-ruby/version.rb

@@ -1,3 +1,3 @@
 module Twilio
-  VERSION = '3.15.1'
+  VERSION = '3.15.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twilio-ruby
 version: !ruby/object:Gem::Version
-  version: 3.15.1
+  version: 3.15.2
 platform: ruby
 authors:
 - Andrew Benton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-18 00:00:00.000000000 Z
+date: 2015-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -119,6 +119,8 @@ files:
 - docs/usage/queues.rst
 - docs/usage/recordings.rst
 - docs/usage/sip.rst
+- docs/usage/taskrouter-tokens.rst
+- docs/usage/taskrouter.rst
 - docs/usage/token-generation.rst
 - docs/usage/transcriptions.rst
 - docs/usage/twiml.rst