bolt githublinkedinservices-title-icon spots swoosh target triangle-icon twilio twitterweave

#TaskRouter - A Case Study

RichardSeptember 15, 2017

What is TaskRouter?

TaskRouter is a means of dynamically assigning pieces of work to the workers that are best placed to handle those tasks. The work is assigned by means of attributes assigned to both the worker and the task requiring action. TaskRouter matches tasks by recognising which workers are best match to each assignment.

Fundamental Objects


A workspace is a logical division within a Twilio account and could be used, for example, to separate organisations within a company. The workspaces act as containers for all the other object types within TaskRouter.


An item of work that requires the attention of TaskRouter. This can be a call, SMS, web chat or whatever task of work your app creates.


The means by which Tasks will be completed.


This is the main action point of a TaskRouter based application. A reservation is raised when TaskRouter has a task for a worker. It then informs your app by making a call to the configured endpoint.


These are used to categorize tasks and describe which workers are able and available to handle the incoming work.

Hunt Group example

The best way to explain TaskRouter is through an example. Our use case here is an app that allows the creation of hunt groups, which are groups of phone numbers belonging to agents that are associated with a single external number. When the external number is called the agents are called in a priority order until the call is answered.

Our app in connection with TaskRouter enables the creation of the hunt groups and associated agents on the fly. Each element of our app is associated with one of the object types in TaskRouter, when we create an object locally we create a corresponding object remotely with the relevant Twilio API call.

Hunt Group

In the app we set up the hunt groups as TaskRouter workflows. On creation of a hunt group we create an associated workflow with the following

def create_workflow
  workflow =
    account_sid: ENV[:account_sid],
    auth_token: client.account_token,
    workspace_sid:  client.workspace_sid

  update(workflow_sid: workflow.create(name).sid)
  • account_sid is the identifier of the Twilio account that we are creating the workflow for
  • auth_token is the security token of the Twilio account
  • workspace_sid is the identifier of the workspace to create the workflow in

After creation we set the hunt group's workflow_sid to that of the newly created one to enable us to call it later.


Agents have be set up as TaskRouter workers. On creation of an agent we set up a new worker as follows:

def create_worker
  worker = twilio_worker_client.create(
      hunt_group: friendly_name,
      priority: 1,
      contact_uri: number

  update(worker_sid: worker.sid)

Here we are setting the worker_name as a chosen friendly name for the agent we are creating. The attributes in hash that we are sending with the request are the list of attributes we wish to assign to the worker.

  • hunt_group the friendly name of the hunt group
  • priority the indicator that dictates in which order the agents should be called
  • contact_uri the phone number of the agent we are creating

Again, after creation, we assign the remote identifier to the local object to be able to call it later.

Incoming calls

Incoming calls are set up as TaskRouter tasks. When a caller dials the number associated with a hunt group Twilio connects to the associated app endpoint for incoming calls. The app then calculates which hunt group is being called based on the number that was dialled and then enqueues the call to the relevant TaskQueue using the following TwiML:

xml.Response do
    workflowSid: @hunt_group.workflow_sid,
    waitUrl: api_twilio_hold_music_url,
    waitUrlMethod: 'POST'
  ) do |e|
    e.Task @attributes.to_json

The details are:

  • response command to specify a response TwiML
  • enqueue command to enqueue the call using the specified attributes
  • workflowSid is used to specify which workflow the call should be assigned to, in this case the one associated with the hunt group that was called
  • waitUrl specifies an endpoint that has hold music that can be played while the caller is on hold
  • waitUrlMethod specifies what method to call the hold music endpoint with, in this case POST

This places the call into a TaskQueue.


Once Twilio has received the response for the app with the relevant TwiML it places the call in the specified workflow. When TaskRouter finds a free worker that is capable of handling the call it will send a request to the Assignment Callback URL that is configured on the workflow. The request includes, among other attributes, the identifier of the task queue that the task has been assigned to, the identifier of the worker that has been assigned the task and the identifier of the reservation.

When the app receives the call it works out which hunt group the task queue is associated with, finds the attribute of the idle activity that will be assigned and responds with the following json:

render json: {
  'instruction' => 'dequeue',
  'from' => caller_number,
  'post_work_activity_sid' => idle_activity.sid,
  'timeout' => 10

The attributes here are:

  • instruction describes what TaskRouter should do with the task, in this case dequeue it to the specified number
  • from the number that the caller is calling from
  • post_work_activity_sid is the state that the assigned worker will be put into once the call has finished. These activities can either make the worker available or unavailable for new calls
  • timeout the number of seconds that TaskRouter will wait for the call to be answered before returning the call into the TaskQueue to be assigned to another worker

This response will 'dequeue' the call from it's queue and call the phone number specified by the contact_uri of the chosen worker. If the call is answered, the task ends once the call has finished. If the call is not answered within the set timeout, the task is put back into the TaskQueue and the next relevant worker is found and the above dequeue process is run again.


Here we have demonstrated a use case of TaskRouter for setting up a Hunt Group Mechanism. This just shows a small example of what can be done with TaskRouter, other examples include a multi-channel contact centre, or whatever use you'd wish to put it to.

For further reading I suggest you check the TaskRouter ruby quickstart and also the features page


out loud

We think out loud on our blog. We share our views on coding, remote work and post regular insights into the freshest tech industry news.

Want more? Join our mailing list.



    Client Engagement

    +44 (0) 20 31 37 63 39

    [email protected]

    So, how can we help you?

    Live chat

    By using this website you agree to our cookie policy