8000 Merge pull request #205 from twilio/document-taskrouter · twilio/twilio-python@6fbf8fe · GitHub
[go: up one dir, main page]
Skip to content

Commit 6fbf8fe

Browse files
skimbrelskimbrel
committed
Merge pull request #205 from twilio/document-taskrouter
Document taskrouter
2 parents 5013577 + 1b26698 commit 6fbf8fe

File tree

16 files changed

+837
-22
lines changed

16 files changed

+837
-22
lines changed

‎docs/api.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ A complete API reference to the :data:`twilio` module.
99

1010
api/rest/index
1111
api/rest/resources
12+
api/rest/resources/task_router
1213
api/twiml
1314
api/util
1415

‎docs/api/rest/index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,6 @@
1818
:members:
1919
:inherited-members:
2020

21+
.. autoclass:: TwilioTaskRouterClient
22+
:members:
23+
:inherited-members:

‎docs/api/rest/resources/task_router.rst

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
.. module:: twilio.rest.resources.task_router
2+
3+
========================================
4+
:mod:`twilio.rest.resources.task_router`
5+
========================================
6+
7+
8+
Workspaces
9+
>>>>>>>>>>
10+
11+
.. autoclass:: Workspaces
12+
:members:
13+
:exclude-members: instance
14+
15+
.. autoclass:: Workspace
16+
17+
Workflows
18+
>>>>>>>>>
19+
20+
.. autoclass:: Workflows
21+
:members:
22+
:exclude-members: instance
23+
24+
.. autoclass:: Workflow
25+
26+
Activities
27+
>>>>>>>>>>
28+
29+
.. autoclass:: Activities
30+
:members:
31+
:exclude-members: instance
32+
33+
.. autoclass:: Activity
34+
.. attribute:: sid
35+
36+
The unique ID for this Activity.
37+
38+
.. attribute:: account_sid
39+
40+
The unique ID of the Account that owns this Activity.
41+
42+
.. attribute:: workspace_sid
43+
44+
The unique ID of the :class:`Workspace` that owns this Activity.
45+
46+
.. attribute:: friendly_name
47+
48+
A human-readable name for the Activity, such as 'on-call', 'break',
49+
'email', etc. These names will be used to calculate and expose
50+
statistics about workers, and give you visibility into the state of
51+
each of your workers.
52+
53+
.. attribute:: available
54+
55+
Boolean value indicating whether the worker should be eligible to
56+
receive a Task when they occupy this Activity. For example, in an
57+
activity called 'On Call', the worker would be unavailable to receive
58+
additional Task assignments.
59+
60+
.. attribute:: date_created
61+
62+
The date this Activity was created, given as UTC in ISO 8601 format.
63+
64+
.. attribute:: date_updated
65+
66+
The date this Activity was last updated, given as UTC in ISO 8601
67+
format.
68+
69+
Workers
70+
>>>>>>>>>>
71+
72+
.. autoclass:: Workers
73+
:members:
74+
:exclude-members: instance
75+
76+
.. autoclass:: Worker
77+
78+
TaskQueues
79+
>>>>>>>>>>
80+
81+
.. autoclass:: TaskQueues
82+
:members:
83+
:exclude-members: instance
84+
85+
.. autoclass:: TaskQueue
86+
87+
Tasks
88+
>>>>>>>>>>
89+
90+
.. autoclass:: Tasks
91+
:members:
92+
:exclude-members: instance
93+
94+
.. autoclass:: Task
95+
96+
Events
97+
>>>>>>>>>>
98+
99+
.. autoclass:: Events
100+
:members:
101+
:exclude-members: instance
102+
103+
.. autoclass:: Event

‎docs/index.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,20 @@ Query the Twilio REST API to create phone calls, send messages and more!
7575
usage/sip
7676

7777

78+
TaskRouter
79+
---------
80+
81+
Query the Twilio TaskRouter API to set up workspaces and task routing, and
82+
create capability tokens to authorize your client-side code to safely update
83+
state.
84+
85+
.. toctree::
86+
:maxdepth: 1
87+
88+
usage/taskrouter
89+
usage/taskrouter-tokens
90+
91+
7892
TwiML
7993
---------
8094

‎docs/usage/taskrouter-tokens.rst

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. module:: twilio.task_router
2+
3+
============================
4+
TaskRouter Capability Tokens
5+
============================
6+
7+
8+
TaskRouter's Worker.js library lets you add `TaskRouter
9+
<https://www.twilio.com/docs/taskrouter>`_ Worker Activity controls
10+
and event notifications to your web applications. Worker.js uses a Websocket
11+
connection to TaskRouter to receive realtime notifications of Worker
12+
Reservations and Task details, and provides a simple API for modifying a
13+
Worker's current Activity.
14+
15+
TaskRouter uses Twilio capability tokens to delegate scoped access to
16+
TaskRouter resources to your JavaScript application. Twilio capability tokens
17+
conform to the JSON Web Token (commonly referred to as a JWT and pronounced
18+
"jot") standard, which allow for limited-time use of credentials by a third
19+
party. Your web server needs to generate a Twilio capability token and provide
20+
it to your JavaScript application in order to register a TaskRouter worker.
21+
22+
:class:`TaskRouterCapability` is responsible for the creation of these
23+
capability tokens. You'll need your Twilio AccountSid and AuthToken,
24+
the Sid of the Workspace you want to authorize access to, and the Sid
25+
of the Worker you're granting authorization for.
26+
27+
.. code-block:: python
28+
29+
from twilio.task_router import TaskRouterCapability
30+
31+
# Get these values from https://twilio.com/user/account
32+
account_sid = "AC123"
33+
auth_token = "secret"
34+
35+
# Create a Workspace and Worker in the TaskRouter account portal
36+
# or through the TaskRouter API
37+
workspace_sid = "WS456"
38+
worker_sid = "WK789"
39+
40+
capability = TaskRouterCapability(account_sid, auth_token,
41+
workspace_sid, worker_sid)
42+
43+
By default, the Capability object will allow the Worker.js process to
44+
read from and write to the websockets used to communicate events, and also
45+
to fetch the list of available activities in the workspace.
46+
47+
There are three additional permissions you can grant using the Capability
48+
token, and in most cases you'll want to allow all of them for your application:
49+
50+
51+
Attribute Fetch
52+
===============
53+
54+
This authorizes requests to retrieve the registered Worker's attributes from
55+
the TaskRouter API.
56+
57+
.. code-block:: python
58+
59+
capability.allow_worker_fetch_attributes()
60+
61+
62+
Worker Activity Update
63+
======================
64+
65+
This authorizes updates to the registered Worker's current Activity.
66+
67+
.. code-block:: python
68+
69+
capability.allow_worker_activity_updates()
70+
71+
72+
Task Reservation Update
73+
=======================
74+
75+
This authorizes updates to a Task's reservation status.
76+
77+
.. code-block:: python
78+
79+
capability.allow_task_reservation_updates()
80+
81+
82+
Generate a Token
83+
================
84+
85+
.. code-block:: python
86+
87+
token = capability.generate_token()
88+
89+
By default, this token will expire in one hour. If you'd like to change the
90+
token expiration, :meth:`generate_token` takes an optional :attr:`ttl`
91+
argument.
92+
93+
.. code-block:: python
94+
95+
token = capability.generate_token(ttl=600)
96+
97+
This token will now expire in 10 minutes. If you haven't guessed already,
98+
:attr:`ttl` is expressed in seconds.
99+
100+
101+
102+
103+
104+

0 commit comments

Comments
 (0)
0