Task Queue Resource

TaskQueues allow you 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. TargetWorkers expressions, described below, control which Workers are eligible to receive Tasks from a given TaskQueue.

Task Assignment Precedence

A TaskQueue will distribute Tasks to any Worker in an 'available' activity that meets the TaskQueue's TargetWorkers criteria. Tasks will be assigned in the following order:

• Higher priority tasks are always assigned before lower priority tasks, regardless of the age of the lower-priority tasks.
• Among tasks of the same priority, the oldest task will always be assigned first.

TaskQueues and Activities

In a multitasking Workspace, a Worker's status does not change as they are assigned and complete Tasks. A Worker's ability to accept a new Task is informed by their active capacity. For single-tasking Workspaces, a Worker is available for a Task based on their activity status. The AssignmentActivitySid and ReservationActivitySid properties can be used to control a Worker's availability during assignment.

When a TaskQueue reserves a Worker for a Task, it places the Worker in the ReservationActivitySid status. If the Worker accepts the Task, the Worker is placed in the AssignmentActivitySid status.

Note that in a single-tasking Workspace, when a Task completes, the Worker's activity does not change. This is because whether or not a Task's completion should change a Worker's activity is dependent on the workflow—the system needs confirmation of the Worker's availability before it will assign Tasks to them again. If this is the experience you want, the easiest way to achieve this is to capture the "task.completed" event and issue an update to the associated Worker's activity at that point.

Actions

• List all TaskQueues
• Create a TaskQueue
• Retrieve a TaskQueue
• Update a TaskQueue
• Delete a TaskQueue

List all TaskQueues

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/TaskQueues

Returns the list of TaskQueues in the workspace identified by {WorkspaceSid}.

Example

List all TaskQueues in a Workspace

Required Parameters

Optional Parameters

Note: The maximum amount of TaskQueues allowed for any given Workspace is 5,000. Please contact us if your use case will require more.

TargetWorkers: Describing Worker Selection Criteria

TaskRouter binds Workers to TaskQueues using the TaskQueue's TargetWorkers expression. TargetWorkers uses an SQL-like expression syntax to filter the Workers in the Workspace.

For example, let's say we have two agents. The first worker, Alice, speaks English and handles Support and Sales Tasks. This is modeled with the following attributes:

'{ "skills": ["support", "sales"], "languages":["english"]}'

The second worker, Bob, handles only Sales requests and speaks Spanish and English:

'{"skills": ["sales"], "languages": ["spanish", "english"]}'

Given these Workers, we can write a TargetWorkers expression to route calls only to Workers with the Support skill who speak English:

(skills HAS "support") AND (languages HAS "english")'

Only Alice would receive tasks from this TaskQueue. We could create a second TaskQueue to route calls to anyone with the Spanish language skill with the TargetWorkers expression:

(languages HAS "spanish")'

And only Bob would receive tasks from this TaskQueue.

Creating TaskQueues

To create TaskQueues with the TargetWorkers expressions explained above, you could issue the following requests:

For the English Support TaskQueue:

curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
-d FriendlyName=EnglishSupport \
-d TargetWorkers='(skills HAS "support") AND (languages HAS "english")' \
-d AssignmentActivitySid={ActivitySid}
-d ReservationActivitySid={ActivitySid}
-u {AccountSid}:{AuthToken}

For the Spanish TaskQueue:

curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
-d FriendlyName=SpanishDefault \
-d TargetWorkers='(languages HAS "spanish")' \
-d AssignmentActivitySid={ActivitySid}
-d ReservationActivitySid={ActivitySid}
-u {AccountSid}:{AuthToken}

Skills-based distribution models, where workers are assigned integer values reflecting their expertise in a given skill, are also possible. The TaskQueues created below use skills-based routing to choose the best worker based on a 'tech_support_skill' attribute:

curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
-d FriendlyName="Tech Support – Tier 1" \
-d TargetWorkers="tech_support_skill < 5" \
-d AssignmentActivitySid={ActivitySid}
-d ReservationActivitySid={ActivitySid}
-u {AccountSid}:{AuthToken}

curl https://taskrouter.twilio.com/v1//Workspaces/{WorkspaceSid}/TaskQueues \
–d FriendlyName="Tech Support - Escalation" \
–d TargetWorkers="tech_support_skill > 5" \
-d AssignmentActivitySid={ActivitySid}
-d ReservationActivitySid={ActivitySid}
-u {AccountSid}:{AuthToken}

To distribute tasks to any Worker, provide an expression that always evaluates to true:

curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues \
–d FriendlyName="Everyone" \
–d TargetWorkers="1==1" \
-u {AccountSid}:{AuthToken}
TargetWorkers: Supported operators

Evaluating Worker Attributes

TaskQueue’s list resource EvaluateWorkerAttributes parameter allows you to view which of your Workers will match a given TargetWorkers expression.

The example below is a way to check which TaskQueues would be mapped to a worker with attributes of tech_support_skill of 6. Using the above example, this should map to Tech Support – Escalation queue.

curl –XGET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues \
--data-urlencode EvaluateWorkerAttributes='{"tech_support_skill": "6"}'
-u {AccountSid}:{AuthToken}

TargetWorkers Operators

You may use the following operators in your TargetWorkers expressions:

• Equality: ==, =
• Inequality: !=
• Greater than: >
• Less than: <
• Greater than or equal to: >=
• Less than or equal to: <=
• Use parentheses to indicate precedence of operations: ( )
• Use brackets to indicate lists/arrays: [ ]
• HAS, >- for determining whether the value of the Worker attribute on the left-hand side of the expression contains the string on the right side of the comparison.
• IN, <- for determining whether the value of the Worker attribute on the left-hand side of the expression is * contained in the list on the right-hand side.
• AND if both the left and right subexpressions are true, resolves to true, otherwise false
• OR - if one or both of the left or right subexpressions are true, resolves to true, otherwise false

Multi-Reservation

A common request is the ability to create reservations for a set of workers in a given queue when a task comes in. You may configure a MaxReservedWorkers parameter on a queue to do just that. When a task routes to a particular queue through a workflow, TaskRouter will create reservations for all workers that are available up to the MaxReservedWorkers parameter. Once one worker accepts the reservation for the task, all other reservations will be rescinded. Any attempts to accept a rescinded reservation, the user will receive a 410 series response, indicating that the reservation can no longer accept the reservation of the task.

For example:

A Task becomes escalated to the "Tech Support - Escalation" TaskQueue, where there are 2 workers available and the MaxReservedWorkers parameter is configured to be 5. A Reservation will be created for each worker - 2 total. An Assignment Callback will be created for each Reservation. An Event Callback will be created for each Reservation creation.

Worker 1 accepts the reservation. Worker 2 will receive a notification that their Reservation is rescinded through the EventCallbackUrl and the JS SDK.

Retrieve a TaskQueue

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}

Return a single TaskQueue resource identified by {TaskQueueSid}.

Example

Example for retreiving a single TaskQueue from a workspace

Resource Properties

A TaskQueue instance resource is represented by the following properties.

Update a TaskQueue

Resource URI

POST /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}

Modifies the TaskQueue. If you modify a TaskQueue and alter its TargetWorkers expression, the Worker statistics associated with this TaskQueue will be reset to reflect the new TargetWorkers. Task statistics for this TaskQueue will remain unchanged.

Example

Example for updating TaskQueue

POST Parameters

You may post the parameters below when modifying a TaskQueue.

Delete a TaskQueue

Resource URI

DELETE /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}

Removes the TaskQueue identified by {TaskQueueSid}.

If associated Workflows' routing logic has recently been updated, pending Tasks may still be processing against this queue, in which case the response will be a 400.

Example

Example for deleting a TaskQueue