Skip to contentSkip to navigationSkip to topbar
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.

Property nameTypeRequiredDescriptionChild properties
account_sidSID<AC>Optional
Not PII

The SID of the Account that created the Workflow resource.

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

assignment_callback_urlstring<uri>Optional

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


configurationstringOptional

A JSON string that contains the Workflow's configuration. See Configuring Workflows for more information.


date_createdstring<date-time>Optional

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

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_typestringOptional

The MIME type of the document.


fallback_assignment_callback_urlstring<uri>Optional

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


friendly_namestringOptional
PII MTL: 30 days

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


sidSID<WW>Optional

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_timeoutintegerOptional

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.

Default: 0

workspace_sidSID<WS>Optional

The SID of the Workspace that contains the Workflow.

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

urlstring<uri>Optional

The absolute URL of the Workflow resource.


linksobject<uri-map>Optional

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
Property nameTypeRequiredPIIDescription
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
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
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 for more information.


AssignmentCallbackUrlstring<uri>Optional

The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.


FallbackAssignmentCallbackUrlstring<uri>Optional

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


TaskReservationTimeoutintegerOptional

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 WorkflowLink to code sample: Create a Workflow
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createWorkflow() {
11
const workflow = await client.taskrouter.v1
12
.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.workflows.create({
14
assignmentCallbackUrl: "https://example.com/",
15
configuration: JSON.stringify({
16
task_routing: {
17
filters: [
18
{
19
expression: "type=='sales'",
20
targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],
21
},
22
{
23
expression: "type=='marketing'",
24
targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],
25
},
26
{
27
expression: "type=='support'",
28
targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],
29
},
30
],
31
default_filter: { queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" },
32
},
33
}),
34
fallbackAssignmentCallbackUrl: "https://example2.com/",
35
friendlyName: "Sales, Marketing, Support Workflow",
36
});
37
38
console.log(workflow.accountSid);
39
}
40
41
createWorkflow();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"assignment_callback_url": "https://example.com/",
4
"configuration": "{\"task_routing\": {\"filters\": [{\"expression\": \"type=='sales'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}, {\"expression\": \"type=='marketing'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}, {\"expression\": \"type=='support'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}], \"default_filter\": {\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}}}",
5
"date_created": "2014-05-14T10:50:02Z",
6
"date_updated": "2014-05-14T23:26:06Z",
7
"document_content_type": "application/json",
8
"fallback_assignment_callback_url": "https://example2.com/",
9
"friendly_name": "Sales, Marketing, Support Workflow",
10
"sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
11
"task_reservation_timeout": 120,
12
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
"workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
"links": {
15
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
16
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",
17
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"
18
}
19
}

Fetch a Workflow resource

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

Property nameTypeRequiredPIIDescription
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
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchWorkflow() {
11
const workflow = await client.taskrouter.v1
12
.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
.fetch();
15
16
console.log(workflow.accountSid);
17
}
18
19
fetchWorkflow();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"assignment_callback_url": "http://example.com",
4
"configuration": "task-routing:\\n - filter: \\n - 1 == 1\\n target:\\n - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n set-priority: 0\\n",
5
"date_created": "2014-05-14T10:50:02Z",
6
"date_updated": "2014-05-14T23:26:06Z",
7
"document_content_type": "application/json",
8
"fallback_assignment_callback_url": null,
9
"friendly_name": "Default Fifo Workflow",
10
"sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
11
"task_reservation_timeout": 120,
12
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
"workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
"links": {
15
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
16
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",
17
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"
18
}
19
}

Read multiple Workflow resources

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

Property nameTypeRequiredPIIDescription
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
Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional

The friendly_name of the Workflow resources to read.


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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listWorkflow() {
11
const workflows = await client.taskrouter.v1
12
.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.workflows.list({ limit: 20 });
14
15
workflows.forEach((w) => console.log(w.accountSid));
16
}
17
18
listWorkflow();

Output

1
{
2
"meta": {
3
"first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0",
4
"key": "workflows",
5
"next_page_url": null,
6
"page": 0,
7
"page_size": 50,
8
"previous_page_url": null,
9
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0"
10
},
11
"workflows": [
12
{
13
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14
"assignment_callback_url": "http://example.com",
15
"configuration": "task-routing:\\n - filter: \\n - 1 == 1\\n target:\\n - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n set-priority: 0\\n",
16
"date_created": "2014-05-14T10:50:02Z",
17
"date_updated": "2014-05-15T16:47:51Z",
18
"document_content_type": "application/json",
19
"fallback_assignment_callback_url": null,
20
"friendly_name": "Default Fifo Workflow",
21
"sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
22
"task_reservation_timeout": 120,
23
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24
"links": {
25
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
26
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",
27
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"
28
},
29
"workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
30
}
31
]
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.
Property nameTypeRequiredPIIDescription
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
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
FriendlyNamestringOptional

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


AssignmentCallbackUrlstring<uri>Optional

The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.


FallbackAssignmentCallbackUrlstring<uri>Optional

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


ConfigurationstringOptional

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.


TaskReservationTimeoutintegerOptional

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.


ReEvaluateTasksstringOptional

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function updateWorkflow() {
11
const workflow = await client.taskrouter.v1
12
.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
.update({ friendlyName: "FriendlyName" });
15
16
console.log(workflow.accountSid);
17
}
18
19
updateWorkflow();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"assignment_callback_url": "http://example.com",
4
"configuration": "task-routing:\\n - filter: \\n - 1 == 1\\n target:\\n - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n set-priority: 0\\n",
5
"date_created": "2014-05-14T10:50:02Z",
6
"date_updated": "2014-05-14T23:26:06Z",
7
"document_content_type": "application/json",
8
"fallback_assignment_callback_url": null,
9
"friendly_name": "FriendlyName",
10
"sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
11
"task_reservation_timeout": 120,
12
"url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
"links": {
14
"statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",
15
"real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",
16
"cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"
17
},
18
"workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
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.

Property nameTypeRequiredPIIDescription
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
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deleteWorkflow() {
11
await client.taskrouter.v1
12
.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
.remove();
15
}
16
17
deleteWorkflow();

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.