Core Concepts: Routing

Twilio Flex uses TaskRouter to distribute calls, messaging sessions, and other types of work to agents in your contact center. It uses Tasks to represent calls, messages or other communications, and to capture all the necessary information for routing them. For every call or message that needs to be handled by a human agent (i.e., it moves past the pre-agent stages like an IVR), a Task should be created using the TaskRouter API. TaskRouter will then route that Task to a suitable agent (also known as a "TaskRouter Worker”).

One customer communication is normally captured by a single Task. Each agent can handle multiple Tasks at a time (a chat with multiple customers for example).

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 with matching attributes 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 TaskRouter step emits Events which log all activity within the Workspace. You can use these events for reporting, or have your applications subscribe to them and trigger new actions.


A Workspace is the container for all other TaskRouter entities (Tasks, Workers, TaskQueues, Workflows, and Activities). Flex supports a single TaskRouter Workspace per Flex account (by default, it is called "Flex Task Assignment").


Workers represent the agents in your contact center who can receive and perform Tasks. The default maximum number of Workers that you can create within the Flex Workspace is 15,000. Read more about Workers in Core Concepts Intro.


A Task represents a unit of work waiting to be performed by a Worker. Typically, Tasks represent communications with an end-customer. For example, a phone call or a web chat conversation. A Task progresses through a series of states, starting with pending, until successfully ending with completed. TaskRouter's primary job with a pending Task is to find an available Worker to handle it.

Each Task carries with it all the information about the engagement — from the caller's number in a voice call to their data entered during an IVR interaction. These can then be surfaced to the agent who accepted the Task, giving them enough context to help the customer. Task assignment is handled by the Workflows within a TaskRouter Workspace.


A Workflow defines the rules for routing Tasks to Workers. A Workflow configuration defines the mechanism for routing Tasks to Queues and Workers, assigning priorities, and escalating when needed. Your Workflow can implement skills-based routing for multi-skilled Workers, prioritized routing, or other common routing models.

Whenever a new Task is added to the Workflow, it will be evaluated against the Workflow configuration. Workflow configuration is defined as JSON and works like a case statement: the Task will be routed based on the first matching TaskRouter Expression.

Task Queues

Task Queues allow you to categorize Tasks and describe which Workers are eligible to handle them. As your Workflow processes a Task, it will pass through one or more Task Queues until the Task is assigned and accepted by an eligible Worker.



Skills refer to abilities that you assign to Workers and apply to your contact center Task Queues and Workflows. They serve as Worker labels and help you sort your contact center users. When adding skills through the UI, Flex displays the resulting expressions which you can apply as a filter on a Queue and Workflow. You assign skills to agents using the Teams View in Flex. When a pending Task comes in, TaskRouter executes your Workflow configuration to find a suitable Worker.


TaskRouter creates a Reservation whenever a Task is reserved for a Worker. Within Flex, agents are notified of incoming voice and messaging Tasks and have the option to accept or reject the Task.


Activities describe the current status of a Worker, which determines whether they are available to receive Task assignments. Workers are always set to a single Activity. Flex ships with default TaskRouter Activities (“Available”, “Unavailable”, “Break”, “Offline”). You can add, remove or change friendly names of Activities in the TaskRouter section of the Twilio Console.


The Availability property of an Activity determines whether a Worker in this Activity is ready to accept new Tasks.

Every TaskRouter Workspace needs to choose a couple of “special” Activities, required for TaskRouter operation. See Activity Resource for more information on TimeoutActivity and DefaultActivity. In addition, the LogoutActivity is the only unbilled Activity on Active User Hour pricing. By default, all of these are set to the Offline Activity.

You can create additional Activities via the Twilio Console or the REST API.

Task Channels

Your Flex contact center can have different types of Tasks, which are separated by Task Channels. Task Channels help TaskRouter identify available Workers who can handle the Task. The default Task Channels created for a Flex account are “default”, “voice”, “chat”, “sms” and “video”.

Worker Capacities and Multitasking

All Flex Workspaces are multitasking, i.e., they allow Workers to handle multiple Tasks in parallel. In a typical contact center environment, agents may be handling both voice calls and messaging requests. While agents can handle just one voice call at a time, you may want them to handle multiple messaging Tasks simultaneously. Multitasking allows you to specify the rules for how Workers can handle multiple Tasks at a time.

Worker capacity for a certain Task Channel defines how many Tasks can be assigned to that Worker at any given time. For example, if John’s capacity for the sms Task Channel is 2, it means that TaskRouter can assign up to 2 SMS-based messaging sessions to John. Further sessions can be assigned once any of the previous ones are completed. You can learn more about Capacity and multitasking in the Worker Channel resource and the Multitasking page.

Ordering Strategies

Task Ordering

You can configure each Task Queue to have one of these Task orders:

  • “First In, First Out” (FIFO) (default) - Tasks are ordered in descending order of priority (highest priority first) and then by ascending order of time (oldest first) i.e. the highest priority Task is picked up first and if there are multiple Tasks of the same priority, the oldest one gets picked up before the others.
  • “Last In, First Out” (LIFO) - Tasks are ordered in descending order of time (newest first) and made available for assignment. Priority is ignored.

If there is a mix of FIFO and LIFO Task Queues on the Workspace, set the Order Priority setting on the Workspace to specify whether FIFO or LIFO Task Queues should be prioritized. For example, if Workspace Order Priority is set to FIFO, and an agent is part of both FIFO and LIFO Task Queues, that agent will be assigned Tasks from the FIFO Task Queues first.

Worker Assignment Ordering

Round-robin assignment is the default worker ordering strategy in Flex TaskRouter Workspaces. This type of ordering means that available Workers receive Tasks proportionally and in circular order, without other factors being evaluated.

Channel-Optimized Routing is a Task Channel setting that isolates Worker assignment for this Task Channel from other Task Channels. When enabled for a Task Channel on a round-robin assignment Workspace, a separate round-robin circle takes effect for that specific Task Channel (e.g. the next Voice call goes to the agent who hasn’t received a Voice call for the longest time). Currently, you can enable Channel-Optimized Routing for a Task Channel only via the REST API.

Activity-based routing is an evaluation pattern that allows you to include or exclude agents based on the Activity that they are in. See this documentation for example use cases and relevant TaskRouter expressions.

More Information

  • How TaskRouter Works - Learn more about TaskRouter's capabilities and get started with TaskRouter Development.
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 our Twilio Community forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more