8000 Add basic usage docs for TaskRouter · madCode/twilio-python@904de8e · GitHub
[go: up one dir, main page]
Skip to content

Commit 904de8e

Browse files
skimbrelskimbrel
committed
Add basic usage docs for TaskRouter
1 parent 11e2226 commit 904de8e

File tree

3 files changed

+341
-0
lines changed

3 files changed

+341
-0
lines changed

‎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/task-router
89+
usage/task-router-tokens
90+
91+
7892
TwiML
7993
---------
8094

‎docs/usage/task-router.rst

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
.. module:: twilio.rest.resources.task_router
2+
3+
==========
4+
TaskRouter
5+
==========
6+
7+
Twilio TaskRouter is a system for distributing tasks such as phone calls,
8+
leads, support tickets, and other work items to the people and processes that
9+
can best handle them.
10+
11+
For more information, see the `TaskRouter documentation
12+
<https://www.twilio.com/docs/taskrouter>_`.
13+
14+
15+
Creating a Workspace
16+
--------------------
17+
18+
A Workspace is a container for your Tasks, Workers, TaskQueues, Workflows and
19+
Activities. Each of these items exists within a single Workspace and will not
20+
be shared across Workspaces.
21+
22+
The following code will create a new :class:`Workspace` resource and print
23+
its unique ID.
24+
25+
.. code-block:: python
26+
27+
from twilio.rest import TwilioTaskRouterClient
28+
29+
# To find these visit https://www.twilio.com/user/account
30+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
31+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
32+
33+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
34+
35+
workspace = client.workspaces.create(
36+
friendly_name="Customer Support",
37+
template="FIFO", # Sets up default activities and a FIFO TaskQueue
38+
)
39+
print workspace.sid
40+
41+
42+
Workflows
43+
---------
44+
45+
Workflows control how tasks will be prioritized and routed into TaskQueues, and
46+
how Tasks should escalate in priority or move across queues over time.
47+
Workflows are described in a simple JSON format and can be modified through the
48+
REST API or through the account portal.
49+
50+
The following code will create a new :class:`Workflow` resource and print its
51+
unique ID:
52+
53+
.. code-block:: python
54+
55+
from twilio.rest import TwilioTaskRouterClient
56+
57+
# To find these visit https://www.twilio.com/user/account
58+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
59+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
60+
61+
# See previous examples to create a Workspace
62+
WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
63+
64+
# Some JSON to configure the Workflow. See the documentation at
65+
# http://www.twilio.com/docs/taskrouter for more details.
66+
CONFIG = """
67+
{
68+
"task_routing":{
69+
"filters":[
70+
{
71+
"friendly_name":"Gold Tickets",
72+
"expression":"customer_value == 'Gold' AND type == 'ticket'",
73+
"targets":[
74+
{
75+
"task_queue_sid":"WQ0123456789abcdef0123456789abcdef",
76+
"priority":"2"
77+
}
78+
]
79+
}
80+
],
81+
"default_filter":{
82+
"task_queue_sid":"WQabcdef01234567890123456789abcdef"
83+
}
84+
}
85+
}
86+
"""
87+
88+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
89+
90+
workspace = client.workflows(WORKSPACE_SID).create(
91+
friendly_name="Incoming Call Flow",
92+
assignment_callback_url="https://example.com/callback",
93+
fallback_assignment_callback_url="https://example.com/callback2",
94+
configuration=CONFIG
95+
)
96+
print workspace.sid
97+
98+
99+
Activities
100+
----------
101+
102+
Activities describe the current status of your Workers, which determines
103+
whether they are eligible to receive task assignments. Workers are always set
104+
to a single Activity.
105+
106+
To create a new :class:`Activity`:
107+
108+
.. code-block:: python
109+
110+
from twilio.rest import TwilioTaskRouterClient
111+
112+
# To find these visit https://www.twilio.com/user/account
113+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
114+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
115+
116+
# See previous examples to create a Workspace
117+
WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
118+
119+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
120+
activity = client.activities(WORKSPACE_SID).create(
121+
friendly_name="Coffee Break",
122+
available=False, # Whether workers are available to handle tasks during this activity
123+
)
124+
125+
126+
Workers
127+
-------
128+
129+
Workers represent an entity that is able to perform tasks, such as an agent
130+
working in a call center, or a salesperson handling leads.
131+
132+
To create a new :class:`Worker`:
133+
134+
.. code-block:: python
135+
136+
from twilio.rest import TwilioTaskRouterClient
137+
138+
# To find these visit https://www.twilio.com/user/account
139+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
140+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
141+
142+
# See previous examples to create a Workspace
143+
WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
144+
145+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
146+
worker = client.workers(WORKSPACE_SID).create(
147+
friendly_name="Jamie",
148+
attributes="""{
149+
"phone": "+14155551234",
150+
"languages": ["EN", "ES"]
151+
}
152+
"""
153+
)
154+
print worker.sid
155+
156+
157+
TaskQueues
158+
----------
159+
160+
TaskQueues are the resource you use to categorize Tasks and describe which
161+
Workers are eligible to handle those Tasks. As your Workflows process Tasks,
162+
those Tasks will pass through one or more TaskQueues until the Task is assigned
163+
and accepted by an eligible Worker.
164+
165+
To create a new :class:`TaskQueue`:
166+
167+
.. code-block:: python
168+
169+
from twilio.rest import TwilioTaskRouterClient
170+
171+
# To find these visit https://www.twilio.com/user/account
172+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
173+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
174+
175+
# See previous examples to create a Workspace
176+
WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
177+
178+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
179+
180+
queue = client.task_queues(WORKSPACE_SID).create(
181+
friendly_name="Sales",
182+
# The Activity to assign workers when a task is reserved for them
183+
reservation_activity_sid="WA11111111111",
184+
# The Activity to assign workers when a task is assigned to them
185+
assignment_activity_sid="WA222222222222",
186+
)
187+
print queue.sid
188+
189+
190+
Tasks
191+
-----
192+
193+
A Task instance resource represents a single item of work waiting to be
194+
processed.
195+
196+
To create a new :class:`Task` via the REST API:
197+
198+
.. code-block:: python
199+
200+
from twilio.rest import TwilioTaskRouterClient
201+
202+
# To find these visit https://www.twilio.com/user/account
203+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
204+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
205+
206+
# See previous examples to create a Workspace
207+
WORKSPACE_SID = "WSZZZZZZZZZZZZZZ"
208+
# Some JSON containing attributes for this task. User-defined.
209+
TASK_ATTRIBUTES = """{
210+
"type": "call",
211+
"contact": "+15558675309",
212+
"customer-value": "gold",
213+
"task-reason": "support",
214+
"callSid": "CA42ed11..."
215+
}"""
216+
217+
218+
client = TwilioTaskRouterClient(ACCOUNT_SID, AUTH_TOKEN)
219+
task = client.tasks(WORKSPACE_SID).create(
220+
attributes=TASK_ATTRIBUTES,
221+
assignment_status='pending',
222+ F438
)
223+
print task.sid

‎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
9+
`TaskRouter<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