Rate this page:

How TaskRouter Works


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. Custom rules can vary assignment based on time spent in queue and case content.
  • Distributing leads to sales teams. TaskRouter's business rules provide control over prioritization so that teams are always working on the most important opportunity.

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

How TaskRouter Works

TaskRouter Diagram

A TaskRouter Workspace is composed of many entities that work together to enable a Task to match a Worker, someone who can take action on the pending Task. This is accomplished through a few steps:

  • Creating a Task and passing it through a Workflow
  • Evaluating a Task's attributes to identify how it should route
  • Routing the Task into a TaskQueue composed of Workers
  • Finding the subset of Workers who have attributes that make them a match for the Task
  • Pairing the Task with a Worker through a Reservation
  • Completing the Reservation once the work represented by the Task is done

Each step taken by TaskRouter emits Events which log all activity within the Workspace. These events can be used for reporting, or applications can subscribe to the events and trigger new actions.

Interacting with TaskRouter in Realtime

The JavaScript SDK is the recommended method for interacting with TaskRouter. Most TaskRouter applications display Task information to agents in a front-end application. The SDK simplifies the process for listening to TaskRouter events and eliminates roundtrips to a backend application attempting to coordinate all TaskRouter activity.

A typical TaskRouter application will:

  • Generate tasks through the REST API or TwiML
  • Have agents logged into an Agent UI, each subscribed to events through the JS SDK
  • Listen to events, like reservation.created, to identify when a Worker has been matched to a Task
  • Complete the reserved Task through the SDK

In addition, applications can listen to Event Callbacks. These JSON web requests cover a wider range of events, and they can be used by back-end services to track information across an entire Workspace. These callbacks can be useful to generate realtime reporting dashboards by aggregating event information, like worker.activity.update and task.completed events.

Automatically Creating and Completing Tasks

TaskRouter is a powerful tool when combined with other Twilio products. For Tasks that represent voice calls, TaskRouter can tie the lifecycle of a call to the lifecycle of a Task. This is particularly useful for automatically adding the assigned Worker as a participant in a Conference with an inbound caller.

Queueing Twilio Calls provides more detail on how to setup these integrations.

Picking the Best Worker

A TaskRouter Workspace is multitasking by default. A Worker's capacity (defined by their WorkerChannels) determines if they can handle three simultaneous chats, a voice call and a chat, or only one voice call.

TaskRouter uses a Worker's capacity and their Activity to determine if they are available for a new Task. When TaskRouter is assigning a Task through a Workflow, it will:

  • Find Workers who match a Task based on attributes defined in a Workflow
  • Ensure selected Workers are in an Available activity and have remaining capacity on the Task's channel
  • Distribute Reservations to the Workers who have been longest without an assignment, or who match a custom-defined sort

Example Application Flow

  • Setup: Create Workers with the appropriate attributes, a TaskQueue associated with the Workers, and a Workflow to control Task assignment and escalation rules.
  • Put all Workers in Offline
  • Create a new Task. The Task will sit in queue until a matching Worker is available.
  • Update a Worker to an Available activity
  • TaskRouter identifies the available Worker and creates a Reservation pairing the Worker with the Task. The Worker's capacity is taken by the pending Reservation.
  • TaskRouter emits a reservation.created event to the JS SDK and as an Event Callback.
  • Respond to the JS event to accept the Reservation.
    • If the Task was a voice call created through <Enqueue>, accept with a conference instruction to automatically bridge the Worker into a Conference with the inbound caller.
  • Complete the Task from the JS SDK once the Worker is finished. The Worker's capacity is released. The process repeats as new Tasks are created.
  • Update the Worker to Offline to end their shift.

Getting Started with TaskRouter Development

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

Rate this page:

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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!