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

Workflow Resource


Workflows control how tasks will be prioritized and routed into Queues, and how Tasks should escalate in priority or move across queues over time. Workflows are described in a simple JSON format and can be modified through the REST API or through the account portal. You can learn more about Workflows here.

You specify which Workflow should control a Task when you add the Task to the Workspace. The Workflow will manage the Task's queue and priority until it is either assigned to a Worker, removed from the queue, or modified.

When a Task is assigned to a Worker, your application will receive a callback to the Workflow's AssignmentCallbackUrl, and your application can then do whatever is required to deliver the Task to the worker (for example, instructing Twilio to dial the phone number of the Worker selected to receive the call). Read more about Task assignment here.


Multiple Workflows

multiple-workflows page anchor

A Workspace can contain multiple Workflows. This allows you to have different sets of routing rules for different types of applications or situations.

For example, a call center has one group of Workers that handles both phone and chat tasks. These two Task types have different service-level targets and agent requirements. They will also originate from separate external applications. To separate application concerns, the call center creates a single Workspace with two separate Workflows, one for phone calls and the other for chat requests.


Creating and Distributing Tasks

creating-and-distributing-tasks page anchor

Whenever you add a Task to a Workspace you indicate which Workflow should route the Task. The Workflow will prioritize the task and place it into a queue, where it will be distributed to the first available Worker that has the necessary capabilities. See the Task Resource for more information.


Handling Task Assignments with the AssignmentCallbackUrl

handling-task-assignments-with-the-assignmentcallbackurl page anchor

Every Workflow has an AssignmentCallbackURL property, as well as a FallbackAssignmentCallbackUrl in case requests to the first URL fail. When a Worker is assigned a Task, TaskRouter will make an HTTP request to this URL. Your application must handle this request to then do whatever is required to connect the Task to the Worker in your application. For example, this might mean pushing a case to an instance of an agent's web application, or dialing an agent's phone number using Twilio. See this section for more information on handling Task Assignment callbacks.

(information)

Info

The AssignmentCallbackUrl is not required if you are planning on using just the JS SDK. In that case, simply leave the value blank.

If we cannot hit your AssignmentCallbackUrl or FallbackAssignmentCallbackUrl, TaskRouter will automatically change your Reservation status to canceled. To get a better sense of how assignment callbacks work, use a tool like Beeceptor(link takes you to an external page) to ensure that the assignment callback is firing correctly and to examine the contents of the post.


(warning)

Warning

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

account_sidSID<AC>
Not PII

The SID of the Account(link takes you to an external page) that created the Workflow resource.

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

assignment_callback_urlstring<uri>

The URL that we call when a task managed by the Workflow is assigned to a Worker. See Assignment Callback URL for more information.


configurationstring

A JSON string that contains the Workflow's configuration. See Configuring Workflows(link takes you to an external page) for more information.


date_createdstring<date-time>

The date and time in GMT when the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedstring<date-time>

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


document_content_typestring

The MIME type of the document.


fallback_assignment_callback_urlstring<uri>

The URL that we call when a call to the assignment_callback_url fails.


friendly_namestring
PII MTL: 30 days

The string that you assigned to describe the Workflow resource. For example, Customer Support or 2014 Election Campaign.


sidSID<WW>

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

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

task_reservation_timeoutinteger

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.


workspace_sidSID<WS>

The SID of the Workspace that contains the Workflow.

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

urlstring<uri>

The absolute URL of the Workflow resource.


linksobject<uri-map>

The URLs of related resources.


Create a Workflow resource

create-a-workflow-resource page anchor
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows

Path parameters

path-parameters page anchor
WorkspaceSidSID<WS>required

The SID of the Workspace that the new Workflow to create belongs to.

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

A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.


Configurationstringrequired

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows(link takes you to an external page) for more information.


AssignmentCallbackUrlstring<uri>

The URL from your application that will process task assignment events. See Handling Task Assignment Callback(link takes you to an external page) for more details.


FallbackAssignmentCallbackUrlstring<uri>

The URL that we should call when a call to the assignment_callback_url fails.


TaskReservationTimeoutinteger

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

Create a Workflow

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

_48
// Download the helper library from https://www.twilio.com/docs/node/install
_48
// Find your Account SID and Auth Token at twilio.com/console
_48
// and set the environment variables. See http://twil.io/secure
_48
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_48
const authToken = process.env.TWILIO_AUTH_TOKEN;
_48
const client = require('twilio')(accountSid, authToken);
_48
_48
client.taskrouter.v1.workspaces('WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_48
.workflows
_48
.create({
_48
assignmentCallbackUrl: 'https://example.com/',
_48
fallbackAssignmentCallbackUrl: 'https://example2.com/',
_48
friendlyName: 'Sales, Marketing, Support Workflow',
_48
configuration: JSON.stringify({
_48
task_routing: {
_48
filters: [
_48
{
_48
expression: `type=='sales'`,
_48
targets: [
_48
{
_48
queue: 'WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_48
}
_48
]
_48
},
_48
{
_48
expression: `type=='marketing'`,
_48
targets: [
_48
{
_48
queue: 'WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_48
}
_48
]
_48
},
_48
{
_48
expression: `type=='support'`,
_48
targets: [
_48
{
_48
queue: 'WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_48
}
_48
]
_48
}
_48
],
_48
default_filter: {
_48
queue: 'WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_48
}
_48
}
_48
})
_48
})
_48
.then(workflow => console.log(workflow.sid));

Output

_51
{
_51
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"assignment_callback_url": "https://example.com/",
_51
"configuration": {
_51
"task_routing": {
_51
"filters": [
_51
{
_51
"expression": "type=='sales'",
_51
"targets": [
_51
{
_51
"queue": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_51
}
_51
]
_51
},
_51
{
_51
"expression": "type=='marketing'",
_51
"targets": [
_51
{
_51
"queue": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_51
}
_51
]
_51
},
_51
{
_51
"expression": "type=='support'",
_51
"targets": [
_51
{
_51
"queue": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_51
}
_51
]
_51
}
_51
],
_51
"default_filter": {
_51
"queue": "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_51
}
_51
}
_51
},
_51
"date_created": "2014-05-14T10:50:02Z",
_51
"date_updated": "2014-05-14T23:26:06Z",
_51
"document_content_type": "application/json",
_51
"fallback_assignment_callback_url": "https://example2.com/",
_51
"friendly_name": "Sales, Marketing, Support Workflow",
_51
"sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"task_reservation_timeout": 120,
_51
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"links": {
_51
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Statistics",
_51
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RealTimeStatistics",
_51
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/CumulativeStatistics"
_51
}
_51
}


Fetch a Workflow resource

fetch-a-workflow-resource page anchor
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

WorkspaceSidSID<WS>required

The SID of the Workspace with the Workflow to fetch.

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

SidSID<WW>required

The SID of the Workflow resource to fetch.

Pattern: ^WW[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
.workflows('WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(workflow => console.log(workflow.friendlyName));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"assignment_callback_url": "http://example.com",
_19
"configuration": "task-routing:\n - filter: \n - 1 == 1\n target:\n - queue: WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n set-priority: 0\n",
_19
"date_created": "2014-05-14T10:50:02Z",
_19
"date_updated": "2014-05-14T23:26:06Z",
_19
"document_content_type": "application/json",
_19
"fallback_assignment_callback_url": null,
_19
"friendly_name": "Default Fifo Workflow",
_19
"sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"task_reservation_timeout": 120,
_19
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"links": {
_19
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Statistics",
_19
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RealTimeStatistics",
_19
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/CumulativeStatistics"
_19
}
_19
}


Read multiple Workflow resources

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

WorkspaceSidSID<WS>required

The SID of the Workspace with the Workflow to read.

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

The friendly_name of the Workflow resources to read.


PageSizeinteger

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

Minimum: 1Maximum: 1000

Pageinteger

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

Minimum: 0

PageTokenstring

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
.workflows
_11
.list({limit: 20})
_11
.then(workflows => workflows.forEach(w => console.log(w.sid)));

Output

_32
{
_32
"meta": {
_32
"first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0",
_32
"key": "workflows",
_32
"next_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows?FriendlyName=friendly_name&PageSize=50&Page=1",
_32
"page": 0,
_32
"page_size": 50,
_32
"previous_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0",
_32
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0"
_32
},
_32
"workflows": [
_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"assignment_callback_url": "http://example.com",
_32
"configuration": "task-routing:\n - filter: \n - 1 == 1\n target:\n - queue: WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n set-priority: 0\n",
_32
"date_created": "2014-05-14T10:50:02Z",
_32
"date_updated": "2014-05-15T16:47:51Z",
_32
"document_content_type": "application/json",
_32
"fallback_assignment_callback_url": null,
_32
"friendly_name": "Default Fifo Workflow",
_32
"sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"task_reservation_timeout": 120,
_32
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Statistics",
_32
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RealTimeStatistics",
_32
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/CumulativeStatistics"
_32
},
_32
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_32
}
_32
]
_32
}


Update a Workflow resource

update-a-workflow-resource page anchor
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

Modifies a Workflow. Whenever you modify a workflow, the following will take place:

  • TaskRouter validates your Workflow configuration to ensure it is syntactically correct and that all queues referenced in the document exist. If any problems are found, the update will fail, and the active Workflow will remain in place.
  • Assuming there are no problems with the configuration provided, TaskRouter will use the previous Workflow to route any Tasks that were pending prior to the change. New Tasks will begin using the updated Workflow immediately.
WorkspaceSidSID<WS>required

The SID of the Workspace with the Workflow to update.

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

SidSID<WW>required

The SID of the Workflow resource to update.

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

A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.


AssignmentCallbackUrlstring<uri>

The URL from your application that will process task assignment events. See Handling Task Assignment Callback(link takes you to an external page) for more details.


FallbackAssignmentCallbackUrlstring<uri>

The URL that we should call when a call to the assignment_callback_url fails.


Configurationstring

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows(link takes you to an external page) for more information.


TaskReservationTimeoutinteger

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.


ReEvaluateTasksstring

Whether or not to re-evaluate Tasks. The default is false, which means Tasks in the Workflow will not be processed through the assignment loop again.

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
.workflows('WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({friendlyName: 'friendly_name'})
_11
.then(workflow => console.log(workflow.friendlyName));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"assignment_callback_url": "http://example.com",
_19
"configuration": "task-routing:\n - filter: \n - 1 == 1\n target:\n - queue: WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n set-priority: 0\n",
_19
"date_created": "2014-05-14T10:50:02Z",
_19
"date_updated": "2014-05-14T23:26:06Z",
_19
"document_content_type": "application/json",
_19
"fallback_assignment_callback_url": null,
_19
"friendly_name": "Default Fifo Workflow",
_19
"sid": "WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"task_reservation_timeout": 120,
_19
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"links": {
_19
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Statistics",
_19
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RealTimeStatistics",
_19
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Workflows/WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/CumulativeStatistics"
_19
},
_19
"workspace_sid": "WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_19
}


Delete a Workflow resource

delete-a-workflow-resource page anchor
DELETE https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

Deletes a Workflow. Will return an error if there are any pending or reserved Tasks still being controlled by this Workflow.

WorkspaceSidSID<WS>required

The SID of the Workspace with the Workflow to delete.

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

SidSID<WW>required

The SID of the Workflow resource to delete.

Pattern: ^WW[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
.workflows('WWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: