Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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.

Worker properties

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.

Names in PHP format
accountSid
sid<AC> Not PII

The ID of the account that owns this worker

activityName
string Not PII

Filter by workers that are in a particular Activity by Friendly Name

activitySid
sid<WA> Not PII

Filter by workers that are in a particular Activity by SID

attributes

JSON object describing this worker. For example: { 'email: 'Bob@foo.com', 'phone': '8675309' }. This data will be passed to the Assignment Callback URL whenever TaskRouter assigns a Task to this worker. Defaults to {}.

available
boolean Not PII

Filter by workers that are available or unavailable. (Note: This can be 'true', '1' or 'yes' to indicate a true value. All other values will represent false)

dateCreated
date_time<iso8601> Not PII

DateTime this worker was created

dateStatusChanged
date_time<iso8601> Not PII

DateTime of the last change to the Worker's activity. Used to calculate Workflow statistics.

dateUpdated
date_time<iso8601> Not PII

DateTime of the last update

friendlyName

Filter by a worker's friendly name

sid
sid<WK> Not PII

The unique ID of the worker

workspaceSid
sid<WS> Not PII

The ID of the Workflow this worker is associated with

url
url Not PII

links
uri_map Not PII

Create a Worker resource

post
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers
Parameters
Names in None format
friendly_name
Required
post string PII MTL: 30 DAYS

String representing user-friendly name for the Worker.

activity_sid
Optional
post sid<WA> Not PII

A valid Activity describing the worker's initial state. See Activities for more information. If not provided, new Workers will be use the DefaultActivitySid configured on the Workspace.

attributes
Optional
post string PII MTL: 30 DAYS

JSON object describing this worker. For example: { 'email: 'Bob@foo.com', 'phone': '8675309' }. This data will be passed to the Assignment Callback URL whenever TaskRouter assigns a Task to this worker. Defaults to {}.

Example
        
        
        
        

        Fetch a Worker resource

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

              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
              Names in None format
              activity_name
              Optional
              get string Not PII

              Filter by workers that are in a particular Activity by Friendly Name

              activity_sid
              Optional
              get sid<WA> Not PII

              Filter by workers that are in a particular Activity by SID

              available
              Optional
              get string Not PII

              Filter by workers that are available or unavailable. (Note: This can be 'true', '1' or 'yes' to indicate a true value. All other values will represent false)

              friendly_name
              Optional
              get string PII MTL: 30 DAYS

              Filter by a worker's friendly name

              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

              Filter by workers that are eligible for a TaskQueue by Friendly Name

              task_queue_sid
              Optional
              get sid<WQ> Not PII

              Filter by workers that are eligible for a TaskQueue by SID

              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

                          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.

                          Example
                                
                                
                                
                                

                                Delete a Worker resource

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

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

                                      Rate this page:

                                      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 browsing the Twilio tag on Stack Overflow.