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.
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.
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.
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.
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 to ensure that the assignment callback is firing correctly and to examine the contents of the post.
Pagination is not supported under this resource. Please avoid usage of the page
query parameter.
The SID of the Account that created the Workflow resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The URL that we call when a task managed by the Workflow is assigned to a Worker. See Assignment Callback URL for more information.
A JSON string that contains the Workflow's configuration. See Configuring Workflows for more information.
The date and time in GMT when the resource was created specified in RFC 2822 format.
The date and time in GMT when the resource was last updated specified in RFC 2822 format.
The URL that we call when a call to the assignment_callback_url
fails.
The string that you assigned to describe the Workflow resource. For example, Customer Support
or 2014 Election Campaign
.
The unique string that we created to identify the Workflow resource.
^WW[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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
.
0
The SID of the Workspace that contains the Workflow.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The URLs of related resources.
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows
The SID of the Workspace that the new Workflow to create belongs to.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
application/x-www-form-urlencoded
A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow
or 2014 Outbound Campaign
.
A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.
The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.
The URL that we should call when a call to the assignment_callback_url
fails.
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
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createWorkflow() {11const workflow = await client.taskrouter.v112.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.workflows.create({14assignmentCallbackUrl: "https://example.com/",15configuration: JSON.stringify({16task_routing: {17filters: [18{19expression: "type=='sales'",20targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],21},22{23expression: "type=='marketing'",24targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],25},26{27expression: "type=='support'",28targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],29},30],31default_filter: { queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" },32},33}),34fallbackAssignmentCallbackUrl: "https://example2.com/",35friendlyName: "Sales, Marketing, Support Workflow",36});3738console.log(workflow.accountSid);39}4041createWorkflow();
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}
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}
The SID of the Workspace with the Workflow to fetch.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Workflow resource to fetch.
^WW[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchWorkflow() {11const workflow = await client.taskrouter.v112.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")14.fetch();1516console.log(workflow.accountSid);17}1819fetchWorkflow();
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}
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows
The SID of the Workspace with the Workflow to read.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listWorkflow() {11const workflows = await client.taskrouter.v112.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.workflows.list({ limit: 20 });1415workflows.forEach((w) => console.log(w.accountSid));16}1718listWorkflow();
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}
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}
Modifies a Workflow. Whenever you modify a workflow, the following will take place:
The SID of the Workspace with the Workflow to update.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Workflow resource to update.
^WW[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
application/x-www-form-urlencoded
A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow
or 2014 Outbound Campaign
.
The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.
The URL that we should call when a call to the assignment_callback_url
fails.
A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.
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
.
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateWorkflow() {11const workflow = await client.taskrouter.v112.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")14.update({ friendlyName: "FriendlyName" });1516console.log(workflow.accountSid);17}1819updateWorkflow();
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 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.
The SID of the Workspace with the Workflow to delete.
^WS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Workflow resource to delete.
^WW[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteWorkflow() {11await client.taskrouter.v112.workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")14.remove();15}1617deleteWorkflow();