Worker Resource
Workers represent an entity that is able to perform tasks, such as an agent working in a call center, or a salesperson handling leads.
The default maximum number of registered Workers that can be created in the system is 15,000.
Worker properties
Pagination is not supported under this resource. Please avoid usage of the page query parameter.
Worker Attributes
Every Worker has a set of Attributes that describe what sort of tasks the Worker is able to complete. Attributes are modeled as a JSON string and may contain string, integer, and array data. These attributes will be used to link a Worker to one or more TaskQueues, and thus determine which Tasks the Worker is eligible to handle.
For example, let's say we have two agents. The first worker, Alice, speaks English and handles Support and Sales Tasks:
{
"skills": ["support", "sales"],
"languages":["english"]
}The second worker, Bob, handles only Sales requests and speaks Spanish and English:
{
"skills": ["sales"],
"languages": ["spanish", "english"]
}A property of contact_uri is required on the WorkerAttributes to indicate whom to call when issuing a Dequeue Instruction.
{
"skills": ["sales"],
"languages": ["spanish", "english"],
"contact_uri": "client:Bob"
}
Worker Activity
Each worker also has an Activity, represented by an ActivitySid. This Activity determines the worker's current state in the system, as well as whether the worker can accept new Task assignments.
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Worker resource. |
activity_name
|
The |
activity_sid
|
The SID of the Worker's current Activity. |
attributes
|
The JSON string that describes the Worker. For example: |
available
|
Whether the Worker is available to perform tasks. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_status_changed
|
The date and time in GMT of the last change to the Worker's activity specified in ISO 8601 format. Used to calculate Workflow statistics. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
friendly_name
|
The string that you assigned to describe the resource. Friendly names are case insensitive, and unique within the TaskRouter Workspace. |
sid
|
The unique string that we created to identify the Worker resource. |
workspace_sid
|
The SID of the Workspace that contains the Worker. |
url
|
The absolute URL of the Worker resource. |
links
|
The URLs of related resources. |
Create a Worker resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace that the new Worker belongs to. |
friendly_name
Required
|
A descriptive string that you create to describe the new Worker. It can be up to 64 characters long. |
activity_sid
Optional
|
The SID of a valid Activity that will describe the new Worker's initial state. See Activities for more information. If not provided, the new Worker's initial state is the |
attributes
Optional
|
A valid JSON string that describes the new Worker. For example: |
Example 1
Fetch a Worker resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Worker to fetch. |
sid
Path
|
The SID of the Worker resource to fetch. |
Example 1
Read multiple Worker resources
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers
By default, this will return the first 50 Workers. Supply a PageSize parameter to fetch more than 50 Workers. See pagination information for more information.
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Workers to read. |
activity_name
Optional
|
The |
activity_sid
Optional
|
The |
available
Optional
|
Whether to return only Worker resources that are available or unavailable. Can be |
friendly_name
Optional
|
The |
target_workers_expression
Optional
|
Filter by Workers that would match an expression on a TaskQueue. This is helpful for debugging which Workers would match a potential queue. |
task_queue_name
Optional
|
The |
task_queue_sid
Optional
|
The SID of the TaskQueue that the Workers to read are eligible for. |
ordering
Optional
|
Sorting parameter for Workers |
Example 1
Example 2
You can use the TargetWorkersExpression parameter to see which workers are eligible for a queue, or to understand why a certain queue isn't mapping to the workers you would expect.
This example checks which workers have a name attribute of Alice, Bob, Connie or David - and, by extension, if we had a queue that mapped to workers with those names, we can be confident that these workers would be associated with the queue.
Update a Worker resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{Sid}
Updating a Worker's current activity is a common operation in any TaskRouter application. You can do this using TaskRouter's Worker.js library, or using this REST API.
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Worker to update. |
sid
Path
|
The SID of the Worker resource to update. |
activity_sid
Optional
|
The SID of a valid Activity that will describe the Worker's initial state. See Activities for more information. |
attributes
Optional
|
The JSON string that describes the Worker. For example: |
friendly_name
Optional
|
A descriptive string that you create to describe the Worker. It can be up to 64 characters long. |
reject_pending_reservations
Optional
|
Whether to reject the Worker's pending reservations. This option is only valid if the Worker's new Activity resource has its |
if_match
Header
|
The If-Match HTTP request header |
Example 1
Delete a Worker resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Worker to delete. |
sid
Path
|
The SID of the Worker resource to delete. |
if_match
Header
|
The If-Match HTTP request header |
Example 1
If you wish to view Reservations for a particular worker, use the Worker Reservation Resource.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
