TaskRouter's primary job with a pending
Task is to find a matching Worker. This assignment is handled by the Workflows within a Workspace.
When created, every Task is associated with a Workflow that is used to evaluate how to find a matching Worker. These Workflow configurations, represented in JSON, trace the path a Task takes until either a Reservation is accepted or the Task is canceled.
This page demonstrates how a Task finds a matching Worker given a Workflow. Workflows Overview provides documentation on how these Workflows can be configured.
1"task_routing": {2"filters": [3{4"expression": "type==\"Support\"",5"filter_friendly_name": "Support Calls",6"targets": [7{8"queue": <Just Support>,9"timeout": 15,10"expression": "worker.id IN task.preferred_agents"11},12{13"timeout": 1514}15]16},17{18"expression": "type==\"Sales\"",19"filter_friendly_name": "Sales Calls",20"targets": [21{22"queue": <Just Sales>,23"timeout": 1524}25]26}27],28"default_filter": {29"queue": <Everyone>30}31}32}
This configuration would be represented in Console like:
A Workflow evaluates linearly from the top to the bottom. A Task will find the first filter that matches that Task's attributes. Within that filter, the Task will then work progressively through each target ("routing step" in Console). A Task will wait in each step for the defined timeout attempting to get an accepted Reservation. If the Task hits the step timeout, it will move to the next step. If the final step is passed without an accepted Reservation, a WorkflowTimeout
event will fire and the Task will be canceled.
The default_filter
is only invoked if a Task doesn't match any filters. In this case, TaskRouter will attempt to find a matching Worker in the Queue defined by default_filter
until the Task reaches its TTL.
Suppose a Task is created for the Workflow defined above with the following attributes:
1{2"type": "Sales"3}
First, the Task would check against the "Support Calls" expression: type==\"Support\""
. Failing that check, the Task then succeeds against the "Sales Calls" expression: "type==\"Sales\""
.
Sales Filter:
1{2"expression": "type==\"Sales\"",3"filter_friendly_name": "Sales Calls",4"targets": [{5"queue": <Just Sales>,6"timeout": 157}]8}
The single routing step attempts to find a matching Worker in the "Just Sales" TaskQueue. This queue has the following Workers Expression: skills HAS "sales"
.
TaskRouter maintains a list of Workers associated with each queue. Here, TaskRouter already knows all Workers which have the sales
skill. While the Task is attempting to be assigned, TaskRouter will filter the Workers in the queue for anyone that is in an Available
activity state. For multitasking Workspaces, TaskRouter will additionally filter the Workers for anyone who has capacity for the Task's channel.
To summarize: the routing step above will find any Worker in the "Just Sales" queue that is Available
and has capacity on the Task's channel.
TaskRouter will create a pending
Reservation for a Worker, choosing Workers in a "round robin" (i.e., a sequential cycle). The new Reservation is sent to the client application in three ways:
reservation.created
event
reservation.created
event will
POST
to the
Event Callback URL
POST
to the
Assignment Callback URL
If the Reservation is accepted, the Task will continue to its following Task States.
If the Reservation doesn't succeed (i.e., the Reservation is rejected or it times out), the Workflow will check the timeout on the routing step. If the Task is still within the timeout, TaskRouter will attempt to assign the Task to any other matching Workers. Otherwise, if the Task is past the routing step timeout, the Task will flow to the next routing step or filter.
If the Worker moves to a different Available
activity state to another while they have Reservations, the Reservations remain with that Worker. This means that a Worker may have Reservations that don't match their new activity state. Reservations stay with the Worker until they are accepted, rejected, or time out.
Suppose a Task is created for the Workflow defined above with the following attributes:
1{2"type": "Support",3"preferred_agents": ["agent01","agent04"]4}
First, the Task would check against the "Support Calls" expression: type==\"Support\""
and succeed.
Support Filter:
1{2"expression": "type==\"Support\"",3"filter_friendly_name": "Support Calls",4"targets": [{5"queue": <Just Support>,6"timeout": 15,7"expression": "worker.id IN task.preferred_agents"8},{9"timeout": 1510}]11}
Similar to the Sales example above, TaskRouter will first find any Worker in the "Just Support" queue that is Available
and has capacity on the Task's channel.
In addition, this routing step has an expression to match a subset of the Workers within the "Just Support' queue. As a result, TaskRouter will only generate a reservation for the Worker identified by "agent01" or "agent04" as a Worker attribute.
Please note, if you would like to target a single known/preferred agent, please use our dedicated Known Agent Routing feature to optimize performance for this use case.
Suppose our support Task is a voice call, and both "agent01" and "agent04" Workers are already on a call. If those Workers have their voice
capacity set to 1, this Task will continue to wait for the 15 seconds timeout.
The sample workflow is simplified for demonstration
In the Workflow above, all Support tasks would wait for 15 seconds attempting to match worker.id IN task.preferred_agents
— even if task.preferred_agents
doesn't exist. This could be more universally addressed with a filter like:
1{2"expression": "preferred_agents != null",3"filter_friendly_name": "Preferred Agents",4"targets": [{5"queue": <Everyone>,6"expression": "worker.id IN task.preferred_agents",7"timeout": 158}]9}
After timeout, the Task will progress to the next routing step:
1{2"timeout": 153}
Although that step doesn't contain a lot of detail, here is how that is rendered in Console:
This second step has inherited the previous step's queue, but this time no matching workers expression is applied — any Available
Worker can match. Therefore this step behaves similarly to the Sales filter from the previous section.
Filter Summary: TaskRouter will first find any Available
Worker in the "Just Support" queue with voice
capacity who has "agent01" or "agent04" as their ID. After 15 seconds without a match, TaskRouter will expand the search to anyone in the same queue for another 15 seconds.
In addition to the standard Workflow features mentioned here, there are additional features that impact how a Task finds a matching Worker.