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
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
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
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 to ensure that the assignment callback is firing correctly and to examine the contents of the post.
Workflow Properties
(warning)
Warning
Pagination is not supported under this resource. Please avoid usage of the page query parameter.
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.
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
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_41
// Download the helper library from https://www.twilio.com/docs/node/install
_41
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_41
_41
// Find your Account SID and Auth Token at twilio.com/console
_41
// and set the environment variables. See http://twil.io/secure
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.
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.