Twilio TaskRouter


TaskRouter is a skills/attribute based routing system.

It is most often used as the ACD (Automatic Call Distribution) engine for a contact center. But it can also be used for many other uses from Business Process Management to IoT.

For Contact Center, it is the engine that can be used for distributing phone calls, chats, emails, leads, support tickets, and other work items to the people that can best handle them. Example applications for TaskRouter include:

  • Distributing calls to call center agents. TaskRouter supports common features required in call center environments, such as skills-based routing and task prioritization.
  • Prioritizing and assigning CRM cases to agents in order to make sure they're handled within service level. TaskRouter lets you specify overflow rules for tasks, allowing you to vary assignment rules based on time spent in queue and case content.
  • Distributing leads to inside sales teams. TaskRouter's business rules allow you to control prioritization so that your team is always working on the most important opportunity.


TaskRouter overview

Want to get straight into code? Dive into the TaskRouter QuickStart here.

The TaskRouter object model

The core concepts can be boiled down to: You create Tasks in the system. Your Workflow decides which TaskQueue that task should wait in, and then which Worker it should be assigned to once a matching worker becomes available.

In more detail:

  • Task: a task represents work that needs to be routed. A task has a priority and a channel type, as well as a set of customizable attributes defined in JSON. The custom attributes can contain whatever you like, such as skills required, skill level required, or context about the customer.
  • Workflow: The Workflow is the brain 
of TaskRouter. The Workflow inspects 
the task to understand 
how to route it, based on Task attributes assigned 
at creation. The Workflow does not just route and forget, but monitors tasks as they’re in the queue. If a task exceeds a defined timeout period without 
being handled, the Workflow can define how to escalate the task. The workflow is defined in JSON, and this is the primary syntax in order to learn about the potential of TaskRouter. You can have multiple workflows routing to the same workers.
  • TaskQueue: TaskQueues represent where tasks wait while waiting for a matching worker to be available to work on the task. They define which workers are eligible to consume tasks from the queue. It is best to think of TaskQueues as primarily a statistics container. There are often routing behaviors that you could create with just one TaskQueue and most of the routing logic in the workflow, or with many TaskQueues. When designing your system, consider TaskQueues as your primary way of filtering out statistics.
  • Workspace: Workspaces are a container for completely separate routing systems, such as distinct contact centers in different departments that never have to interact. In most cases you would be better to create a different account/project to represent your separation of e.g. dev/stage/prod or different contact center deployments.

How TaskRouter works

The workflow will execute your logic on each Task you create, and place the task into a queue. For any worker who is available and has free capacity, TaskRouter will look for a task which they are eligible to work on. When there are multiple tasks the worker could work on, TaskRouter will select the longest waiting of the highest priority tasks (if the queue is FIFO), or the shortest waiting task (if the queue is LIFO).

When a Task is matched to a Worker, TaskRouter makes a reservation request for your worker. If your worker is registered using the TaskRouter JavaScript SDK (preferred) then you will receive this reservation as an event on the SDK. You can also configure a webhook destination for assignment to come as an HTTP callback to your web application, informing your application of the reservation. If your agents are sitting in front of a web user interface, the JavaScript SDK mechanism is the recommended approach.

Your application (either server side or client side) is then responsible for replying with an assignment instruction to tell TaskRouter how to deliver the work to the agent (for example, telling Twilio to bridge two callers) or implementing your own Task bridging logic and then accepting the reservation (for example, accepting a sales lead in a CRM, sending an email, etc). To learn more about the possible assignment instructions, read an overview of them here.

How workflow decides on the match

Workers and Tasks both have "attributes" fields. These fields are ad hoc JSON objects that describe the task or the worker. A task might have a field "required_language" with a value of "spanish". A worker might have an attribute "spoken_languages" with a value of ["english", "spanish", "french"]. TaskRouter uses these attributes to route each Task to a Worker eligible to handle it.

A Workflow might have a rule that says "if the task has {"required_language": "spanish", "type": "sales"} as its attribute, then put that Task in the TaskQueue with the spanish speaking sales workers."

Finally, we have Worker capacity. Tasks can be assigned to be of different channels (types) - for example voice, sms, chat. Workers can be configured to handle particular volumes of each task type simultaneously, for example a worker might be able to handle one voice call and three chat sessions at the same time. Note that when a worker can handle more than one task at a time, their availability will show as 'idle' even if they are working on something, because they are not at max capacity. Workers can also be set manually to other availability (presence) states, such as "Offline" or "Busy". Read more about multi-tasking here.

Example TaskRouter application flow

  • Your application creates one or more Workers with the appropriate attributes, a TaskQueue to hold their Tasks, and a Workflow to control Task priorities and escalation rules.
  • Your application puts one of your Workers in the "Offline" Activity.
  • Your application adds a new Task to your Workflow. This Task will sit in queue until a Worker is available.
  • Your application updates a Worker's Activity to "Idle".
  • TaskRouter, seeing a Worker is in an available Activity and is eligible to handle the Task, reserves the Worker and Task. The Worker will not receive any new Task assignments until the reservation has a response.
  • Your agent is looking at an Agent User Interface you have built which includes the TaskRouter JS SDK, and the SDK is connected with a token created for that worker. TaskRouter raises an event on the SDK for a new reservation, telling your application about the reservation that was just created.
  • Your application accepts or rejects the Reservation by replying with instructions on how to connect the Task with the Worker, or implementing your own custom connection logic.
  • For example, if the task is a Twilio phone call, you can respond with an instruction:conference and tell Twilio to bridge the call to the Worker and set it up ready for multi-party call control in the future.
  • Once the call finishes, the task will move into wrapup/wrapping state. This means the worker has not yet freed up that capacity to be assigned a new task so they can take time to write notes etc.
  • Once the Worker completes the Task, they free up capacity and the process repeats.

Getting started with TaskRouter development

Want to get started quickly? Dive into the TaskRouter QuickStart here.

You can integrate TaskRouter into your applications and manage TaskRouter through the following APIs:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.