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

Loading Code Sample...
      
      
          
          
          
          
        


      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.

      Loading Code Sample...
          
          
              
              
              
              
            

          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.

          Loading Code Sample...
              
              
                  
                  
                  
                  
                
              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.

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    

                  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.

                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        

                      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.

                      Loading Code Sample...
                          
                          
                              
                              
                              
                              
                            

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

                          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.

                          Loading Code Sample...