Skip to content Skip to navigation Skip to topbar

On this page

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

(warning)

Warning

Worker attribute values do not support hyphens. Using a hyphen in a worker attribute value may cause a parsing error.

(warning)

Warning

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:

1{ 
2    "skills": ["support", "sales"], 
3    "languages":["english"]
4}

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

1{ 
2    "skills": ["sales"], 
3    "languages": ["spanish", "english"]
4}

(information)

Info

A property of contact_uri is required on the WorkerAttributes to indicate whom to call when issuing a Dequeue Instruction.

1{ 
2    "skills": ["sales"], 
3    "languages": ["spanish", "english"],
4    "contact_uri": "client\:Bob"
5}
6

(warning)

Warning

The Teams page uses the worker attribute team_sid. If you have any custom implementations in Flex, do not use the same team_sid worker attribute.

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.

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The SID of the Account that created the Worker resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

activityNamestring

Optional

The friendly_name of the Worker's current Activity.

activitySidSID<WA>

Optional

The SID of the Worker's current Activity.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34

attributesstring

Optional

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.

availableboolean

Optional

Whether the Worker is available to perform tasks.

dateCreatedstring<date-time>

Optional

The date and time in GMT when the resource was created specified in ISO 8601 format.

dateStatusChangedstring<date-time>

Optional

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.

dateUpdatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

friendlyNamestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource. Friendly names are case insensitive, and unique within the TaskRouter Workspace.

sidSID<WK>

Optional

The unique string that we created to identify the Worker resource.

Pattern: ^WK[0-9a-fA-F]{32}$Min length: 34Max length: 34

workspaceSidSID<WS>

Optional

The SID of the Workspace that contains the Worker.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

urlstring<uri>

Optional

The absolute URL of the Worker resource.

linksobject<uri-map>

Optional

The URLs of related resources.

Create a Worker resource

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

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace that the new Worker belongs to.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

friendlyNamestring

required

PII MTL: 30 days

A descriptive string that you create to describe the new Worker. It can be up to 64 characters long.

activitySidSID<WA>

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 default_activity_sid configured on the Workspace.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34

attributesstring

Optional

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 {}.

Create a Worker

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createWorker() {
11  const worker = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.create({ friendlyName: "FriendlyName" });
14
15  console.log(worker.accountSid);
16}
17
18createWorker();

Response

1{
2  "sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "friendly_name": "FriendlyName",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "activity_sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "activity_name": "Offline",
7  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "attributes": "{}",
9  "available": false,
10  "date_created": "2017-05-30T23:19:38Z",
11  "date_updated": "2017-05-30T23:19:38Z",
12  "date_status_changed": "2017-05-30T23:19:38Z",
13  "operating_unit_sid": "OUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "consumed_concurrency": 0,
15  "consumed_attention": 0,
16  "configured_concurrency": -1,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
20    "activity": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics",
23    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
24    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
25    "worker_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
26    "worker_channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
27    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
28  }
29}

Fetch a Worker resource

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

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the Worker to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

sidSID<WK>

required

The SID of the Worker resource to fetch.

Pattern: ^WK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch a Worker

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchWorker() {
11  const worker = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers("WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .fetch();
15
16  console.log(worker.accountSid);
17}
18
19fetchWorker();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "activity_name": "available",
4  "activity_sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "attributes": "{}",
6  "available": false,
7  "date_created": "2017-05-30T23:32:39Z",
8  "date_status_changed": "2017-05-30T23:32:39Z",
9  "date_updated": "2017-05-30T23:32:39Z",
10  "friendly_name": "NewWorker3",
11  "sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "operating_unit_sid": "OUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "consumed_concurrency": 0,
14  "consumed_attention": 0,
15  "configured_concurrency": -1,
16  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
20    "activity": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics",
23    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
24    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
25    "worker_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
26    "worker_channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
27    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
28  }
29}

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.

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the Workers to read.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

Property nameTypeRequiredPIIDescription

activityNamestring

Optional

The activity_name of the Worker resources to read.

activitySidSID<WA>

Optional

The activity_sid of the Worker resources to read.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34

availablestring

Optional

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.

friendlyNamestring

Optional

PII MTL: 30 days

The friendly_name of the Worker resources to read.

targetWorkersExpressionstring

Optional

Filter by Workers that would match an expression. In addition to fields in the workers' attributes, the expression can include the following worker fields: sid, friendly_name, activity_sid, or activity_name

taskQueueNamestring

Optional

The friendly_name of the TaskQueue that the Workers to read are eligible for.

taskQueueSidSID<WQ>

Optional

The SID of the TaskQueue that the Workers to read are eligible for.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

orderingstring

Optional

Sorting parameter for Workers

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List all Workers

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listWorker() {
11  const workers = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.list({ limit: 20 });
14
15  workers.forEach((w) => console.log(w.accountSid));
16}
17
18listWorker();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers?Available=available&TargetWorkersExpression=target_workers_expression&TaskQueueName=task_queue_name&ActivityName=activity_name&ActivitySid=WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&TaskQueueSid=WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&FriendlyName=friendly_name&PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers?Available=available&TargetWorkersExpression=target_workers_expression&TaskQueueName=task_queue_name&ActivityName=activity_name&ActivitySid=WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&TaskQueueSid=WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&FriendlyName=friendly_name&PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "workers"
10  },
11  "workers": [
12    {
13      "sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "friendly_name": "testWorker",
15      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "activity_sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "activity_name": "Offline",
18      "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19      "attributes": "{}",
20      "available": false,
21      "date_created": "2017-05-30T23:05:29Z",
22      "date_updated": "2017-05-30T23:05:29Z",
23      "date_status_changed": "2017-05-30T23:05:29Z",
24      "operating_unit_sid": "OUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "consumed_concurrency": 0,
26      "consumed_attention": 0,
27      "configured_concurrency": -1,
28      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29      "links": {
30        "channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
31        "activity": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32        "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33        "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics",
34        "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
35        "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
36        "worker_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
37        "worker_channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
38        "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
39      }
40    }
41  ]
42}

List Workers with Target Expression

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listWorker() {
11  const workers = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers.list({
14      targetWorkersExpression: "name IN ['Alice','Bob','Connie','David']",
15      limit: 20,
16    });
17
18  workers.forEach((w) => console.log(w.accountSid));
19}
20
21listWorker();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers?Available=available&TargetWorkersExpression=target_workers_expression&TaskQueueName=task_queue_name&ActivityName=activity_name&ActivitySid=WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&TaskQueueSid=WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&FriendlyName=friendly_name&PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers?Available=available&TargetWorkersExpression=target_workers_expression&TaskQueueName=task_queue_name&ActivityName=activity_name&ActivitySid=WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&TaskQueueSid=WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&FriendlyName=friendly_name&PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "workers"
10  },
11  "workers": [
12    {
13      "sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "friendly_name": "testWorker",
15      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "activity_sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "activity_name": "Offline",
18      "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19      "attributes": "{}",
20      "available": false,
21      "date_created": "2017-05-30T23:05:29Z",
22      "date_updated": "2017-05-30T23:05:29Z",
23      "date_status_changed": "2017-05-30T23:05:29Z",
24      "operating_unit_sid": "OUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "consumed_concurrency": 0,
26      "consumed_attention": 0,
27      "configured_concurrency": -1,
28      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29      "links": {
30        "channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
31        "activity": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32        "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33        "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics",
34        "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
35        "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
36        "worker_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
37        "worker_channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
38        "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
39      }
40    }
41  ]
42}

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.

Headers

Property nameTypeRequiredPIIDescription

ifMatchstring

Optional

The If-Match HTTP request header

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the Worker to update.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

sidSID<WK>

required

The SID of the Worker resource to update.

Pattern: ^WK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

activitySidSID<WA>

Optional

The SID of a valid Activity that will describe the Worker's initial state. See Activities for more information.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34

attributesstring

Optional

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 {}.

friendlyNamestring

Optional

PII MTL: 30 days

A descriptive string that you create to describe the Worker. It can be up to 64 characters long.

rejectPendingReservationsboolean

Optional

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.

Update a Worker

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateWorker() {
11  const worker = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers("WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({ activitySid: "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" });
15
16  console.log(worker.accountSid);
17}
18
19updateWorker();

Response

1{
2  "sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "friendly_name": "blah",
4  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "activity_sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "activity_name": "Offline",
7  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8  "attributes": "{}",
9  "available": false,
10  "date_created": "2017-05-30T23:32:22Z",
11  "date_updated": "2017-05-31T00:05:57Z",
12  "date_status_changed": "2017-05-30T23:32:22Z",
13  "operating_unit_sid": "OUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "consumed_concurrency": 0,
15  "consumed_attention": 0,
16  "configured_concurrency": -1,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
20    "activity": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/Statistics",
23    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/RealTimeStatistics",
24    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/CumulativeStatistics",
25    "worker_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
26    "worker_channels": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
27    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workers/WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
28  }
29}

Delete a Worker resource

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

Headers

Property nameTypeRequiredPIIDescription

ifMatchstring

Optional

The If-Match HTTP request header

Path parameters

Property nameTypeRequiredPIIDescription

workspaceSidSID<WS>

required

The SID of the Workspace with the Worker to delete.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

sidSID<WK>

required

The SID of the Worker resource to delete.

Pattern: ^WK[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete a Worker

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteWorker() {
11  await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .workers("WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .remove();
15}
16
17deleteWorker();

(information)

Info

If you wish to view Reservations for a particular worker, use the Worker Reservation Resource.