Route Tasks Even Faster with TaskRouter Multi-Reservation

April 29, 2015
Written by
Al Cook

Twilio Bug Logo

We built TaskRouter to help customers solve a recurring problem: matching tasks to the right people or processes that can best handle them. Developers have started to use TaskRouter to build everything from multi-channel call centers to rich CRM integrations. Today we’re excited to announce an enhancement to TaskRouter that makes it possible to route tasks and get them completed even more quickly.

We have learned from customers that some tasks benefit from a “first to respond” distribution model. This might be because the task has a really short shelf-life and needs to be handled immediately, or because the task is overdue (for example TaskRouter escalated it to an “urgent and overdue” TaskQueue). Either way, the desired behavior is to offer the task to multiple workers, enabling whoever responds first get it.

The default behavior of TaskRouter is to reserve a single available worker, wait for that worker to accept or reject the task, and then move on to the next worker in the event of a rejection. This task lifecycle looks like this:

Task created → assigned to Workflow → routed to TaskQueue → Worker reserved → Reservation accepted → Task assigned to Worker

Starting today, TaskRouter’s new multi-reservation feature offers a task to a group of eligible workers, and lets the first to accept the task handle the work. Developers can adjust this behavior by modifying a new property on the TaskQueue resource called MaxReservedWorkers.


Screenshot 2015-04-28 19.33.49

The MaxReservedWorkers property tell a TaskQueue the maximum number of workers to reserve for a task. It defaults to 1, which is the classic behavior for TaskRouter. But now developers can increase this value, up to a maximum of 50.

Let’s walk through an example inspired by the TaskRouter Quickstart where we have a TaskQueue and two workers, Alice and Bob. Let’s see what happens if the MaxReservedWorkers is set to 5 and a task comes in.

If Bob and Alice are idle, TaskRouter will create two reservations, one for each of the Workers. The web application will receive two HTTP requests to the Workflow’s Assignment Callback URL: one for Bob’s reservation and one for Alice’s. It is now up to the web application to tell Task Router which Worker is going to accept the reservation. Let’s say that this will be Alice.

To indicate that Alice has accepted the Task, the web application will make an HTTP POST request to the Reservation resource:

curl -X POST{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid} \

-d ReservationStatus=accepted \

-u {AccountSid}:{AuthToken}


Examining the response from TaskRouter, we see that the Task Reservation has been accepted, and the Task has been assigned to the our Worker Alice:

{... "worker_name": "Alice", "reservation_status": "accepted", ...}

Now, perhaps both Alice and Bob would like to accept the Task, but Alice was faster. If Bob attempts to accept the Reservation, the HTTP request will fail with a HTTP 410 Gone response. This happens because Bob’s reservation is no longer actionable. Once Alice accepted her reservation, Bob’s reservation was no longer valid and was disposed of.
We are excited about this enhancement to TaskRouter and hope you that you enjoy routing and completing tasks quicker than ever. For more documentation on how this new feature works, please see the TaskQueue and Worker.js documentation.