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`	sid<AC> Not PII The SID of the Account that created the Worker resource.
`activity_name`	string Not PII The `friendly_name` of the Worker's current Activity.
`activity_sid`	sid<WA> Not PII The SID of the Worker's current Activity.
`attributes`	string PII MTL: 30 DAYS The JSON string that describes the Worker. For example: `{ "email": "Bob@example.com", "phone": "+5095551234" }`. Note If this property has been assigned a value, it will only be displayed in FETCH actions that return a single resource. Otherwise, this property will be null, even if it has a value. This data is passed to the `assignment_callback_url` when TaskRouter assigns a Task to the Worker.
`available`	boolean Not PII Whether the Worker is available to perform tasks.
`date_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_status_changed`	date_time<iso8601> Not PII 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`	date_time<iso8601> Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`friendly_name`	string PII MTL: 30 DAYS The string that you assigned to describe the resource. Friendly names are case insensitive, and unique within the TaskRouter Workspace.
`sid`	sid<WK> Not PII The unique string that we created to identify the Worker resource.
`workspace_sid`	sid<WS> Not PII The SID of the Workspace that contains the Worker.
`url`	url Not PII The absolute URL of the Worker resource.
`links`	uri_map Not PII The URLs of related resources.

Create a Worker resource

post

https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers

Parameters

Parameters in REST API format
`workspace_sid` Path	post sid<WS> Not PII The SID of the Workspace that the new Worker belongs to.
`friendly_name` Required	post string PII MTL: 30 DAYS A descriptive string that you create to describe the new Worker. It can be up to 64 characters long.
`activity_sid` Optional	post sid<WA> Not PII 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 `default_activity_sid` configured on the Workspace.
`attributes` Optional	post string PII MTL: 30 DAYS A valid JSON string that describes the new Worker. For example: `{ "email": "Bob@example.com", "phone": "+5095551234" }`. This data is passed to the `assignment_callback_url` when TaskRouter assigns a Task to the Worker. Defaults to {}.

Example 1

Loading Code Sample...

Example JSON response

Create Worker

Fetch a Worker resource

get

https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{Sid}

Parameters

Parameters in REST API format
`workspace_sid` Path	get sid<WS> Not PII The SID of the Workspace with the Worker to fetch.
`sid` Path	get sid<WK> Not PII The SID of the Worker resource to fetch.

Parameters in REST API format

workspace_sid

Path

get sid<WS> Not PII

The SID of the Workspace with the Worker to fetch.

sid

Path

get sid<WK> Not PII

The SID of the Worker resource to fetch.

Example 1

Loading Code Sample...

Example JSON response

Fetch Worker

Read multiple Worker resources

get

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	get sid<WS> Not PII The SID of the Workspace with the Workers to read.
`activity_name` Optional	get string Not PII The `activity_name` of the Worker resources to read.
`activity_sid` Optional	get sid<WA> Not PII The `activity_sid` of the Worker resources to read.
`available` Optional	get string Not PII Whether to return only Worker resources that are available or unavailable. Can be `true`, `1`, or `yes` to return Worker resources that are available, and `false`, or any value returns the Worker resources that are not available.
`friendly_name` Optional	get string PII MTL: 30 DAYS The `friendly_name` of the Worker resources to read.
`target_workers_expression` Optional	get string Not PII 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	get string Not PII The `friendly_name` of the TaskQueue that the Workers to read are eligible for.
`task_queue_sid` Optional	get sid<WQ> Not PII The SID of the TaskQueue that the Workers to read are eligible for.
`ordering` Optional	get string Not PII Sorting parameter for Workers

Example 1

Loading Code Sample...

Example JSON response

List all Workers

Example 2

Loading Code Sample...

Example JSON response

List Workers with Target Expression

You can use the TargetWorkersExpression parameter to see which workers are matching the expression, 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

post

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	post sid<WS> Not PII The SID of the Workspace with the Worker to update.
`sid` Path	post sid<WK> Not PII The SID of the Worker resource to update.
`activity_sid` Optional	post sid<WA> Not PII The SID of a valid Activity that will describe the Worker's initial state. See Activities for more information.
`attributes` Optional	post string PII MTL: 30 DAYS The JSON string that describes the Worker. For example: `{ "email": "Bob@example.com", "phone": "+5095551234" }`. This data is passed to the `assignment_callback_url` when TaskRouter assigns a Task to the Worker. Defaults to {}.
`friendly_name` Optional	post string PII MTL: 30 DAYS A descriptive string that you create to describe the Worker. It can be up to 64 characters long.
`reject_pending_reservations` Optional	post boolean Not PII Whether to reject the Worker's pending reservations. This option is only valid if the Worker's new Activity resource has its `availability` property set to `False`.
`if_match` Header	post string Not PII The If-Match HTTP request header

Example 1

Loading Code Sample...

Example JSON response

Update Worker

Delete a Worker resource

delete

https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{Sid}

Parameters

Parameters in REST API format
`workspace_sid` Path	delete sid<WS> Not PII The SID of the Workspace with the Worker to delete.
`sid` Path	delete sid<WK> Not PII The SID of the Worker resource to delete.
`if_match` Header	delete string Not PII The If-Match HTTP request header

Parameters in REST API format

workspace_sid

Path

delete sid<WS> Not PII

The SID of the Workspace with the Worker to delete.

sid

Path

delete sid<WK> Not PII

The SID of the Worker resource to delete.

if_match

Header

delete string Not PII

The If-Match HTTP request header

Example 1

Loading Code Sample...

Example JSON response

Delete Worker

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.

Worker properties

Create a Worker resource

Parameters

Example 1

Create Worker

Fetch a Worker resource

Parameters

Example 1

Fetch Worker

Read multiple Worker resources

Parameters

Example 1

List all Workers

Example 2

List Workers with Target Expression

Update a Worker resource

Parameters

Example 1

Update Worker

Delete a Worker resource

Parameters

Example 1

Delete Worker

Need some help?

Thank you for your feedback!

Need help? Talk to Support

Thanks for your feedback!