Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Task Resource


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 Properties

task-properties page anchor
(warning)

Warning

Pagination is not supported under this resource. Please avoid usage of the page query parameter.

Task Attributes

task-attributes page anchor

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:


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

Tasks have a version, represented in the ETag header when you POST or GET the Task Resource. ETags are a method of showing whether a resource has changed; if the ETag is the same, then the resource is the same.

Tasks can also use the If-Match header when updating or deleting a Task Resource. If the ETag does not match the provided version, the operation will fail with a 412 response. You can then GET the latest version of the Task and try updating it again. When the If-Match is not provided, the Task will update without a check.

You can read about Task Mutation and Conflict Resolution to learn about working with Task versions.

A Task does not have an explicit Lifecycle property, but it's an important concept for understanding how Tasks work. A Task's lifecycle is controlled by a Workflow, which will manage the Task's priority and find matching Workers to handle the Task. The Task State page and Workflows and Assignment page provide more detail on the Task lifecycle.

(information)

Info

If you wish to update the assignment status of a task to wrapping or completed and also update its attributes, you will need to send two API requests: one for changing the assignment status, and one for updating the attributes.

Property nameTypePIIDescription
account_sidSID<AC>
Not PII

The SID of the Account that created the Task resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

ageinteger

The number of seconds since the Task was created.


assignment_statusenum<string>

The current status of the Task's assignment. Can be: pending, reserved, assigned, canceled, wrapping, or completed.

Possible values:
pendingreservedassignedcanceledcompletedwrapping

attributesstring
PII MTL: 30 days

The JSON string with custom attributes of the work. Note If this property has been assigned a value, it will only be displayed in FETCH action that returns a single resource. Otherwise, it will be null.


addonsstring

An object that contains the Add-on data for all installed Add-ons.


date_updatedstring<date-time>

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


task_queue_entered_datestring<date-time>

The date and time in GMT when the Task entered the TaskQueue, specified in ISO 8601(link takes you to an external page) format.


priorityinteger

The current priority score of the Task as assigned to a Worker by the workflow. Tasks with higher priority values will be assigned before Tasks with lower values.


reasonstring

The reason the Task was canceled or completed, if applicable.


sidSID<WT>

The unique string that we created to identify the Task resource.

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34

task_queue_sidSID<WQ>

The SID of the TaskQueue.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

task_queue_friendly_namestring

The friendly name of the TaskQueue.


task_channel_sidSID<TC>

The SID of the TaskChannel.

Pattern: ^TC[0-9a-fA-F]{32}$Min length: 34Max length: 34

task_channel_unique_namestring

The unique name of the TaskChannel.


timeoutinteger

The amount of time in seconds that the Task can live before being assigned.


workflow_sidSID<WW>

The SID of the Workflow that is controlling the Task.

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34

workflow_friendly_namestring

The friendly name of the Workflow that is controlling the Task.


workspace_sidSID<WS>

The SID of the Workspace that contains the Task.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

urlstring<uri>

The absolute URL of the Task resource.


linksobject<uri-map>

The URLs of related resources.


virtual_start_timestring<date-time>

The date and time in GMT indicating the ordering for routing of the Task specified in ISO 8601(link takes you to an external page) format.


ignore_capacityboolean

A boolean indicating if a new task should respect a worker's capacity during assignment


routing_targetstring

A SID of a Worker, Queue, or Workflow to route a Task to


POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required

The SID of the Workspace that the new Task belongs to.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
TimeoutintegerOptional

The amount of time in seconds the new task can live before being assigned. Can be up to a maximum of 2 weeks (1,209,600 seconds). The default value is 24 hours (86,400 seconds). On timeout, the task.canceled event will fire with description Task TTL Exceeded.


PriorityintegerOptional

The priority to assign the new task and override the default. When supplied, the new Task will have this priority unless it matches a Workflow Target with a Priority set. When not supplied, the new Task will have the priority of the matching Workflow Target. Value can be 0 to 2^31^ (2,147,483,647).


TaskChannelstringOptional

When MultiTasking is enabled, specify the TaskChannel by passing either its unique_name or sid. Default value is default.


WorkflowSidSID<WW>Optional

The SID of the Workflow that you would like to handle routing for the new Task. If there is only one Workflow defined for the Workspace that you are posting the new task to, this parameter is optional.

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34

AttributesstringOptional

A URL-encoded JSON string with the attributes of the new task. This value is passed to the Workflow's assignment_callback_url when the Task is assigned to a Worker. For example: { "task_type": "call", "twilio_call_sid": "CAxxx", "customer_ticket_number": "12345" }.


VirtualStartTimestring<date-time>Optional

The virtual start time to assign the new task and override the default. When supplied, the new task will have this virtual start time. When not supplied, the new task will have the virtual start time equal to date_created. Value can't be in the future.


RoutingTargetstringOptional

A SID of a Worker, Queue, or Workflow to route a Task to


IgnoreCapacitystringOptional

A boolean indicating if a new task should respect a worker's capacity during assignment


TaskQueueSidSID<WQ>Optional

The SID of the TaskQueue in which the Task belongs

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create a Task

create-a-task page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.tasks
_13
.create({attributes: JSON.stringify({
_13
type: 'support'
_13
}), workflowSid: 'WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'})
_13
.then(task => console.log(task.sid));

Output

_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"age": 25200,
_33
"assignment_status": "pending",
_33
"attributes": {
_33
"type": "support"
_33
},
_33
"date_created": "2014-05-14T18:50:02Z",
_33
"date_updated": "2014-05-15T07:26:06Z",
_33
"task_queue_entered_date": null,
_33
"virtual_start_time": "2014-05-14T18:50:02Z",
_33
"priority": 1,
_33
"reason": "Test Reason",
_33
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_unique_name": "unique",
_33
"timeout": 60,
_33
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_friendly_name": "Example Workflow",
_33
"task_queue_friendly_name": "Example Task Queue",
_33
"ignore_capacity": false,
_33
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"addons": {},
_33
"links": {
_33
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_33
}
_33
}

(warning)

Warning

Please contact us(link takes you to an external page) if your use case will require more than 25,000 in-flight Tasks for any given Workspace. We define in-flight Tasks as all Tasks that are not in status canceled or completed.


GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks/{Sid}

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required

The SID of the Workspace with the Task to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<WT>required

The SID of the Task resource to fetch.

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.tasks('WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(task => console.log(task.taskQueueFriendlyName));

Output

_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"age": 25200,
_33
"assignment_status": "pending",
_33
"attributes": {
_33
"body": "hello"
_33
},
_33
"date_created": "2014-05-14T18:50:02Z",
_33
"date_updated": "2014-05-15T07:26:06Z",
_33
"task_queue_entered_date": "2014-05-14T18:50:02Z",
_33
"virtual_start_time": "2014-05-14T18:50:02Z",
_33
"priority": 0,
_33
"reason": "Test Reason",
_33
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_unique_name": "task-channel",
_33
"timeout": 60,
_33
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_friendly_name": "Test Workflow",
_33
"task_queue_friendly_name": "Test Queue",
_33
"ignore_capacity": false,
_33
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"addons": {},
_33
"links": {
_33
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_33
}
_33
}


Read multiple Task resources

read-multiple-task-resources page anchor
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required

The SID of the Workspace with the Tasks to read.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
PriorityintegerOptional

The priority value of the Tasks to read. Returns the list of all Tasks in the Workspace with the specified priority.


AssignmentStatusarray[string]Optional

The assignment_status of the Tasks you want to read. Can be: pending, reserved, assigned, canceled, wrapping, or completed. Returns all Tasks in the Workspace with the specified assignment_status.


WorkflowSidSID<WW>Optional

The SID of the Workflow with the Tasks to read. Returns the Tasks controlled by the Workflow identified by this SID.

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34

WorkflowNamestringOptional

The friendly name of the Workflow with the Tasks to read. Returns the Tasks controlled by the Workflow identified by this friendly name.


TaskQueueSidSID<WQ>Optional

The SID of the TaskQueue with the Tasks to read. Returns the Tasks waiting in the TaskQueue identified by this SID.

Pattern: ^WQ[0-9a-fA-F]{32}$Min length: 34Max length: 34

TaskQueueNamestringOptional

The friendly_name of the TaskQueue with the Tasks to read. Returns the Tasks waiting in the TaskQueue identified by this friendly name.


EvaluateTaskAttributesstringOptional

The attributes of the Tasks to read. Returns the Tasks that match the attributes specified in this parameter.


RoutingTargetstringOptional

A SID of a Worker, Queue, or Workflow to route a Task to


OrderingstringOptional

How to order the returned Task resources. By default, Tasks are sorted by ascending DateCreated. This value is specified as: Attribute:Order, where Attribute can be either DateCreated, Priority, or VirtualStartTime and Order can be either asc or desc. For example, Priority:desc returns Tasks ordered in descending order of their Priority. Pairings of sort orders can be specified in a comma-separated list such as Priority:desc,DateCreated:asc, which returns the Tasks in descending Priority order and ascending DateCreated Order. The only ordering pairing not allowed is DateCreated and VirtualStartTime.


HasAddonsbooleanOptional

Whether to read Tasks with Add-ons. If true, returns only Tasks with Add-ons. If false, returns only Tasks without Add-ons.


PageSizeintegerOptional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.tasks
_11
.list({limit: 20})
_11
.then(tasks => tasks.forEach(t => console.log(t.sid)));

Output

_46
{
_46
"meta": {
_46
"first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0",
_46
"key": "tasks",
_46
"next_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=1",
_46
"page": 0,
_46
"page_size": 50,
_46
"previous_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0",
_46
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0"
_46
},
_46
"tasks": [
_46
{
_46
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"age": 25200,
_46
"assignment_status": "pending",
_46
"attributes": {
_46
"body": "hello"
_46
},
_46
"date_created": "2014-05-14T14:26:54Z",
_46
"date_updated": "2014-05-15T16:03:42Z",
_46
"task_queue_entered_date": "2014-05-14T14:26:54Z",
_46
"virtual_start_time": "2014-05-14T14:26:54Z",
_46
"priority": 0,
_46
"reason": "Test Reason",
_46
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_channel_unique_name": "task-channel",
_46
"timeout": 60,
_46
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow_friendly_name": "Test Workflow",
_46
"task_queue_friendly_name": "Test Queue",
_46
"ignore_capacity": false,
_46
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"addons": {},
_46
"links": {
_46
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_46
}
_46
}
_46
]
_46
}

Fetches all Tasks which have a language attribute of 'en' or 'fr' and a 'skill_rating' attribute with value greater than 5.1

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.tasks
_14
.list({
_14
evaluateTaskAttributes: `(language == "en" OR language == "fr") AND skill_rating >= 5.1`,
_14
limit: 20
_14
})
_14
.then(tasks => tasks.forEach(t => console.log(t.sid)));

Output

_46
{
_46
"meta": {
_46
"first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0",
_46
"key": "tasks",
_46
"next_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=1",
_46
"page": 0,
_46
"page_size": 50,
_46
"previous_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0",
_46
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks?TaskQueueSid=WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&RoutingTarget=WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TaskQueueName=task_queue_name&WorkflowName=workflow_name&WorkflowSid=WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AssignmentStatus=pending%2Creserved&Priority=1&PageSize=50&Page=0"
_46
},
_46
"tasks": [
_46
{
_46
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"age": 25200,
_46
"assignment_status": "pending",
_46
"attributes": {
_46
"body": "hello"
_46
},
_46
"date_created": "2014-05-14T14:26:54Z",
_46
"date_updated": "2014-05-15T16:03:42Z",
_46
"task_queue_entered_date": "2014-05-14T14:26:54Z",
_46
"virtual_start_time": "2014-05-14T14:26:54Z",
_46
"priority": 0,
_46
"reason": "Test Reason",
_46
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"task_channel_unique_name": "task-channel",
_46
"timeout": 60,
_46
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow_friendly_name": "Test Workflow",
_46
"task_queue_friendly_name": "Test Queue",
_46
"ignore_capacity": false,
_46
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"addons": {},
_46
"links": {
_46
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_46
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_46
}
_46
}
_46
]
_46
}

(information)

Info

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.

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.
  • CONTAINS - for determining whether the value of the Task attribute on the left-hand side of the expression contains the value 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.
  • NOT IN , <- for determining whether the value of the Task attribute on the left-hand side of the expression is * not 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

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


POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks/{Sid}

Property nameTypeRequiredPIIDescription
If-MatchstringOptional

If provided, applies this mutation if (and only if) the ETag(link takes you to an external page) header of the Task matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header(link takes you to an external page).

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required

The SID of the Workspace with the Task to update.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<WT>required

The SID of the Task resource to update.

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
AttributesstringOptional

The JSON string that describes the custom attributes of the task.


AssignmentStatusenum<string>Optional

The new status of the task. Can be: canceled, to cancel a Task that is currently pending or reserved; wrapping, to move the Task to wrapup state; or completed, to move a Task to the completed state.

Possible values:
pendingreservedassignedcanceledcompletedwrapping

ReasonstringOptional

The reason that the Task was canceled or completed. This parameter is required only if the Task is canceled or completed. Setting this value queues the task for deletion and logs the reason.


PriorityintegerOptional

The Task's new priority value. When supplied, the Task takes on the specified priority unless it matches a Workflow Target with a Priority set. Value can be 0 to 2^31^ (2,147,483,647).


TaskChannelstringOptional

When MultiTasking is enabled, specify the TaskChannel with the task to update. Can be the TaskChannel's SID or its unique_name, such as voice, sms, or default.


VirtualStartTimestring<date-time>Optional

The task's new virtual start time value. When supplied, the Task takes on the specified virtual start time. Value can't be in the future.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = require('twilio')(accountSid, authToken);
_17
_17
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_17
.tasks('WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_17
.update({
_17
assignmentStatus: 'canceled',
_17
reason: 'waiting too long',
_17
attributes: JSON.stringify({
_17
type: 'other'
_17
})
_17
})
_17
.then(task => console.log(task.taskQueueFriendlyName));

Output

_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"age": 25200,
_33
"assignment_status": "canceled",
_33
"attributes": {
_33
"type": "other"
_33
},
_33
"date_created": "2014-05-14T18:50:02Z",
_33
"date_updated": "2014-05-15T07:26:06Z",
_33
"task_queue_entered_date": "2014-05-14T18:50:02Z",
_33
"virtual_start_time": "2023-08-02T12:34:56Z",
_33
"priority": 0,
_33
"reason": "waiting too long",
_33
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_unique_name": "task-channel",
_33
"timeout": 60,
_33
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_friendly_name": "Test Workflow",
_33
"task_queue_friendly_name": "Test Queue",
_33
"addons": {},
_33
"ignore_capacity": false,
_33
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"links": {
_33
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_33
}
_33
}

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.

Check for version match before updating a Task

check-for-version-match-before-updating-a-task page anchor

Use the If-Match header to check Task Version

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.tasks('WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.update({
_15
ifMatch: '0',
_15
assignmentStatus: 'canceled',
_15
reason: 'waiting too long'
_15
})
_15
.then(task => console.log(task.taskQueueFriendlyName));

Output

_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"age": 25200,
_33
"assignment_status": "canceled",
_33
"attributes": {
_33
"body": "hello"
_33
},
_33
"date_created": "2014-05-14T18:50:02Z",
_33
"date_updated": "2014-05-15T07:26:06Z",
_33
"task_queue_entered_date": "2014-05-14T18:50:02Z",
_33
"virtual_start_time": "2023-08-02T12:34:56Z",
_33
"priority": 0,
_33
"reason": "waiting too long",
_33
"sid": "WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_queue_sid": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_sid": "TCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"task_channel_unique_name": "task-channel",
_33
"timeout": 60,
_33
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow_friendly_name": "Test Workflow",
_33
"task_queue_friendly_name": "Test Queue",
_33
"addons": {},
_33
"ignore_capacity": false,
_33
"routing_target": "WKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"links": {
_33
"task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/TaskQueues/WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tasks/WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Reservations"
_33
}
_33
}

The previous version of Etag can be found in the client by accessing the following attribute:

client.httpClient.lastResponse.headers.etag


DELETE https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Tasks/{Sid}

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

Property nameTypeRequiredPIIDescription
If-MatchstringOptional

If provided, deletes this Task if (and only if) the ETag(link takes you to an external page) header of the Task matches the provided value. This matches the semantics of (and is implemented with) the HTTP If-Match header(link takes you to an external page).

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required

The SID of the Workspace with the Task to delete.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<WT>required

The SID of the Task resource to delete.

Pattern: ^WT[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.tasks('WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();

Check for version match before deleting a Task

check-for-version-match-before-deleting-a-task page anchor

Use the If-Match header to check Task Version

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.tasks('WTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove({ifMatch: '0'});


Rate this page: