Menu

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?

REST API: Workers

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 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"]
}

Note: 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.

List All Workers

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Workers

Returns the list of Workers for the Workspace {WorkspaceSid}.

Note: By default, this will return the first 50 Workers. Supply a PageSize parameter to fetch more than 50 Workers. See paging for more information.

Example

Example for listing all workers in workspace

        
        
        
        


        List Filters

        The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

        Field Description
        FriendlyName Filter by a worker’s friendly name
        TaskQueueSid Filter by workers that are eligible for a TaskQueue by SID
        TaskQueueName Filter by workers that are eligible for a TaskQueue by Friendly Name
        ActivitySid Filter by workers that are in a particular Activity by SID
        ActivityName Filter by workers that are in a particular Activity by Friendly Name
        Available 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)
        TargetWorkersExpression Filter by workers that would match an expression on a TaskQueue. This is helpful for debugging which workers would match a potential queue.
        Example

        Example for filtering workers in a workspace.

              
              
              
              

              Target Workers Expression

              Worker’s list resource TargetWorkersExpression parameter allows you to view which workers would be eligible for a queue based on potential queue expression. This is a way of previewing which workers a queue would be eligible for or debugging why a certain queue isn’t mapping to the workers you would expect.

              The example below is a way to check which workers would be mapped to a queue with an expression of any worker that has a name attribute of Alice, Bob, Connie or David.

              curl –XGET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers \
              -d TargetWorkersExpression="name IN ['Alice','Bob','Connie','David']"
              -u {AccountSid}:{AuthToken}
              


              Create a Worker

              Resource URI

              POST /v1/Workspaces/{WorkspaceSid}/Workers
              

              Creates a Worker.

              Example

              Example for creating a worker in workspace.

                    
                    
                    
                    
                    Required Parameters
                    Field Description
                    FriendlyName String representing user-friendly name for the Worker. (📇 PII )
                    Optional Parameters
                    Field Description
                    ActivitySid 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. (🏢 not PII )
                    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 {}. (📇 PII )

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


                    Retrieve a Worker

                    GET /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}
                    

                    Returns a single Worker resource identified by {WorkerSid}.

                    Example

                    Example for retrieving a Worker from Workspace.

                          
                          
                          
                          

                          Resource Properties

                          A Worker instance resource is represented by the following properties.

                          Field Description
                          Sid The unique ID of the worker
                          AccountSid The ID of the account that owns this worker
                          WorkspaceSid The ID of the Workflow this worker is associated with
                          FriendlyName A user-friendly name for the worker.
                          Attributes JSON object describing this Worker. For example, for a Worker that handles English language phone calls: '{"language":"english","task-type":"phone"}'. These attributes determine which TaskQueue this worker will subscribe to. These attributes will also be passed to the Assignment Callback URL whenever TaskRouter assigns a Task to this worker, so you can also use this as a place to store information that you'll need when routing a Task to the Worker (for example, the Worker's phone number or Twilio Client name).
                          Available Boolean value indicating whether the worker can be assigned another task. When true the worker can be assigned a new Task; when false the worker will not be assigned any Tasks.
                          ActivitySid The ID of the Activity this Worker is currently performing.
                          ActivityName String describing the worker's current activity, for example 'on-call', 'after-call-work', 'break', etc. Workers may only perform Activities that exist in this Workspace. See the Activites Resource for more information.
                          DateCreated DateTime this worker was created
                          DateUpdated DateTime of the last update
                          DateStatusChanged DateTime of the last change to the Worker's activity. Used to calculate Workflow statistics.


                          Update a Worker

                          POST /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}
                          

                          Updates a single Worker resource identified by {WorkerSid}.

                          Example

                          Example for updating a worker.

                                
                                
                                
                                

                                POST Parameters

                                You may use the following parameters when modifying a Worker resource.

                                Field Description
                                FriendlyName String representing user-friendly name for the Worker. (📇 PII )
                                Attributes JSON object describing this Worker. For example, for a Worker that handles English language phone calls: '{"language":"english","task-type":"phone"}'. These attributes determine which TaskQueue this worker will subscribe to. These attributes will also be passed to the Assignment Callback URL whenever TaskRouter assigns a Task to this worker, so you can also use this as a place to store information that you'll need when routing a Task to the Worker (for example, the Worker's phone number or Twilio Client name). (📇 PII )
                                ActivitySid The ID of the Activity this Worker is currently performing. Note that if there is a pending reservation for the worker, the ActivitySid cannot be updated until the Reservation is accepted or rejected. (🏢 not PII )
                                Updating a Worker's current activity

                                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.

                                For example, using the REST API:

                                curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid} \
                                -d ActivitySid={ActivitySid} \
                                -u {AccountSid}:{AuthToken}
                                

                                Or using Worker.js:

                                worker.updateActivity("WAxxx", function(error, worker) {
                                  if(error) {
                                    console.log(error.code);
                                    console.log(error.message);
                                  } else {
                                    console.log(worker.activity_name); // "Offline"
                                  }
                                });
                                

                                Note: A 409 Conflict HTTP response may be returned for simultaneous updates to an individual Worker. This indicates one update is already in progress.


                                Delete a Worker

                                DELETE /v1/Workspaces/{WorkspaceSid}/Workers/{WorkerSid}
                                

                                Removes the worker identified by {WorkerSid}

                                Example

                                Example for deleting a worker.

                                      
                                      
                                      
                                      

                                      Note: If you wish to view Reservations for a particular worker, you can do here.

                                      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.