Menu

Expand
Rate 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

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

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

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

        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.

        Example 1
        Loading Code Sample...
              
              

              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. In addition to fields in the workers' attributes, the expression can include the following worker fields: sid, friendly_name, activity_sid, or activity_name

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

                    List all Workers

                    Example 2
                    Loading Code Sample...
                          
                          

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

                                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

                                Example 1
                                Loading Code Sample...
                                      
                                      

                                      Delete Worker

                                      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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                      Loading Code Sample...
                                            
                                            
                                            

                                            Thank you for your feedback!

                                            Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                            Sending your feedback...
                                            🎉 Thank you for your feedback!
                                            Something went wrong. Please try again.

                                            Thanks for your feedback!

                                            thanks-feedback-gif