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?

REST API: Tasks

A Task represents a single item of work waiting to be processed. Tasks can represent whatever type of work is important for your team. Twilio applications can create tasks from phone calls or SMS messages. Your CRM or ticketing system can generate tasks from emails or chat messages sent in by your customers. Your own applications can create custom tasks representing whatever unique work your users handle.

Task Attributes

Every Task has attributes, allowing you to pass along whatever data is required for your application to route the task and take the appropriate action on assignment. Attributes are expressed in JSON data, for example:

{ 
  "type": "call", 
  "contact": "+15558675309", 
  "customer-value": "gold", 
  "task-reason": "support", 
  "callSid": "CA42ed11..." 
}

Task Lifecycle

A Task's lifecycle is controlled by a Workflow, which will manage the Task's priority and find matching Workers to handle the Task. Task State and Workflows and Assignment provide more detail on the Task lifecycle.

Actions


List all Tasks

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Tasks

Returns a list of Tasks waiting in the Workspace identified by {WorkspaceSid} with oldest Task on top.

Example

Example for listing all Tasks in a workspace

        
        
        
        
        Optional Parameters

        When listing Tasks, you can optionally pass the following parameter:

        Parameter Description
        Ordering Use this parameter to control the order of the Tasks returned. The value should be passed in Attribute:Order format, where Attribute can be either Priority or DateCreated and Order can be either asc or desc. For example, Priority:desc returns Tasks ordered by Priority in descending order. To sort the Tasks by Priority and DateCreated pass Priority:desc,DateCreated:asc. By Default Tasks are returned sorted by DateCreated in ascending order.

        Note: You'll receive a 4xx response, if Attribute value doesn't match either Priority or DateCreated or Order doesn't match either asc or desc.

        List Filters

        Field Description
        Priority Retrieve the list of all Tasks in the workspace with the specified priority.
        AssignmentStatus Returns the list of all Tasks in the workspace with the specified AssignmentStatus. Allowed AssignmentStatus values are pending, reserved, assigned, wrapping, canceled, and completed.
        WorkflowSid Returns the list of Tasks that are being controlled by the Workflow with the specified Sid value.
        WorkflowName Returns the list of Tasks that are being controlled by the Workflow with the specified FriendlyName value.
        TaskQueueSid Returns the list of Tasks that are currently waiting in the TaskQueue identified by the Sid specified.
        TaskQueueName Returns the list of Tasks that are currently waiting in the TaskQueue identified by the FriendlyName specified.
        EvaluateTaskAttributes Provide a task attributes expression, and this will return tasks which match the attributes.
        Example

        Example for listing Tasks in Pending state

              
              
              
              

              The below GET requests fetches all Tasks which have a language attribute of "en" or "fr" and a "skill_rating" attribute with value greater than 5.1

              curl –XGET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks \
              --data-urlencode EvaluateTaskAttributes='(language == \"en\" OR language == \"fr\") AND skill_rating >= 5.1'
              -u {AccountSid}:{AuthToken}
              

              You may use the following operators in your EvaluateTaskAttributes:

              • Equality: ==, =
              • Inequality: !=
              • Greater than: >
              • Less than: <
              • Greater than or equal to: >=
              • Less than or equal to: <=
              • Use parentheses to indicate precedence of operations: ( )
              • Use brackets to indicate lists/arrays: [ ]
              • HAS, >- for determining whether the value of the Task attribute on the left-hand side of the expression contains the string on the right side of the comparison.
              • IN, <- for determining whether the value of the Task attribute on the left-hand side of the expression is * contained in the list on the right-hand side.
              • AND if both the left and right subexpressions are true, resolves to true, otherwise false
              • OR - if one or both of the left or right subexpressions are true, resolves to true, otherwise false Note: By default, this will return the first 50 Tasks. Supply a PageSize parameter to fetch more than 50 Tasks. See paging for more information.

              Important: Tasks are deleted 5 minutes after either they are canceled or completed. You can still query events that occurred for a Task via the Events API.


              Create a Task

              Resource URI

              POST /v1/Workspaces/{WorkspaceSid}/Tasks
              

              Creates a new Task.

              Example

              Example for creating a new Task

                    
                    
                    
                    
                    Required Parameters
                    Parameter Description
                    Attributes Url-encoded JSON string describing the attributes of this task. An example task: { "task_type": "call", "twilio_call_sid": "CAxxx", "customer_ticket_number": "12345" } (📇 PII )
                    WorkflowSid The WorkflowSid for the Workflow that you would like to handle routing for this Task. If there is only one Workflow defined for the Workspace that you are posting a task to, then this is an optional parameter, and that single workflow will be used. (🏢 not PII )

                    Example: Create a Task by POSTing the task and its attributes to the Workflow that you want to use to route the Task. For example:

                    Optional Parameters

                    When creating a Task, you can optional POST the following parameter:

                    Parameter Description
                    TaskChannel When Multitasking is enabled specify the type of the task by passing either TaskChannel Unique Name or Task Channel Sid. Default value is “default” (🏢 not PII )
                    Timeout The amount of time in seconds the task is allowed to live up to a maximum of 2 weeks. Defaults to 24 hours. On timeout, task.canceled event will fire with description "Task TTL Exceeded". (🏢 not PII )
                    Priority Override priority for the Task. When supplied, the Task will take on the given priority unless it matches a Workflow Target with a Priority set. When not supplied, the Task will take on the priority of the matching Workflow Target. (🏢 not PII )

                    Note: The maximum amount of in-flight Tasks allowed for any given Workspace is 500,000. Please contact us if your use case will require more.


                    Retrieve a Task

                    Resource URI

                    GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}
                    

                    Returns a representation of the Task specified by {TaskSid}.

                    Example

                    Example for retrieving a single Task

                          
                          
                          
                          

                          Resource Properties

                          A Task instance resource is represented by the following properties:

                          Field Description
                          Sid The unique ID of the Task
                          AccountSid The ID of the account that owns this Task
                          WorkspaceSid The ID of the Workspace that holds this Task
                          WorkflowSid The ID of the Workflow responsible for routing this Task
                          Attributes The user-defined JSON string describing the custom attributes of this work.
                          Age The number of seconds since this task was created.
                          Priority The current priority score of the task, as assigned by the workflow. Tasks with higher values will be assigned before tasks with lower values.
                          TaskQueueSid The current Queue the Task occupies, controlled by the Workflow's Workflow.
                          AssignmentStatus A string representing the Assignment State of the task. May be pending, reserved, assigned, canceled or completed. See the table of Task Assignment Status values below for more information.
                          Reason The reason the task was canceled or completed (if applicable)
                          DateCreated Date this task was created, given as ISO 8601 format.
                          DateUpdated Date this task was updated, given as ISO 8601 format.
                          Timeout The amount of time in seconds the task is allowed to live
                          TaskChannelSid The ID of the Task Channel
                          TaskChannelUniqueName The unique name of the Task Channel
                          Addons The addon data for all installed addons is returned with this attribute

                          The following are the possible values for the AssignmentStatus parameter.

                          Status Description
                          pending The Task is available for a worker and is waiting to be assigned. No worker has been selected to handle this task.
                          reserved A worker has been selected to handle this Task, but has not yet confirmed receipt of the Task.
                          assigned A worker has been selected and confirmed receipt of this Task.
                          canceled The task has been canceled before it could be assigned.
                          completed The task has been completed.

                          Update a Task

                          Resource URI

                          POST /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}
                          

                          Updates the Task identified by {TaskSid}.

                          Example

                          Example for updating Task

                                
                                
                                
                                

                                POST Parameters

                                Field Description
                                Attributes The user-defined JSON data describing the custom attributes of this task. (📇 PII )
                                AssignmentStatus A 'pending' or 'reserved' Task may be canceled by posting AssignmentStatus='canceled'. Post AssignmentStatus='wrapping' to move Task to 'wrapup' state and AssignmentStatus='completed' to move a Task to 'completed' state. (🏢 not PII )
                                Reason This is only required if the Task is canceled or completed. This logs the reason the task was either canceled or completed and queues the task for deletion after 5 minutes. (🏢 not PII )
                                Priority Override priority for the Task. When supplied, the Task will take on the given priority unless it matches a Workflow Target with a Priority set. (🏢 not PII )

                                Important: When a pending Task's attributes are updated, the Task will be re-driven through the Workflow identified by the WorkflowSid associated with the task. Depending on the Workflow's filters, TaskRouter may move the Task into a different TaskQueue. The age of the Task will remain the same. If the Task is moved to a new TaskQueue, its TaskQueue position relative to other tasks will be determined by its age and priority, as usual.


                                Delete a Task

                                Resource URI

                                DELETE /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}
                                

                                Deletes the Task identified by {TaskSid}. For all pending reservations associated with the deleted Task, these will also be deleted at task deletion time.

                                Example

                                Example for deleting a Task

                                      
                                      
                                      
                                      

                                      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.