Twilio TaskRouter


Twilio TaskRouter is a system for distributing tasks such as phone calls, leads, support tickets, and other work items to the people and processes 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.

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

How TaskRouter works

TaskRouter enables you to manage a set of Workers, a set of Tasks, and the configuration that determines how the Tasks are matched and distributed to Workers. When a Task is matched to a Worker, TaskRouter makes an HTTP callback to your web application, informing your application of the reservation. Your application is then responsible for replying and telling 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).

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.

This Task Routing is accomplished through two other TaskRouter concepts: Workflows and TaskQueues. These entities represent the routing and queueing rules of the system. TaskQueues are simply collections of Tasks for a set of Workers that have attributes matching a certain criteria (I.E. can speak spanish and handle sales leads). Workflows are a series of rules that inspect incoming Tasks and place them into TaskQueues. For example, 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 Activities and availability. Each worker has an Activity, this can be one of the default activities, such as "Offline", "Idle", "Reserved", and "Busy" or a custom Activity you create. Each activity has an "availability", which is either true or false. A Worker who is available can receive tasks assigments (Idle for example). Workers who are not available cannot receive task assignments (Reserved, Busy, Offline).

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, preventing the Worker from receiving any new Task assignments until it has responded.
  • TaskRouter makes an HTTP callback to your application, 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 and tell Twilio to bridge the call to the Worker.
  • Or, if the Task is a ticket in your CRM system, your application carries out the required actions to assign the ticket to the Worker, and then informs TaskRouter that the Worker has accepted the Task.
  • Once the Worker completes the Task, you update the Worker's Activity to the "Idle" state, and the process repeats. Alternatively, you could set the Worker's Activity to "Wrapping up" to allow them a short break, or "Offline" to end their shift.

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: