Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Queueing Twilio calls with TaskRouter



Introduction

introduction page anchor

Want to use TaskRouter and TwiML to implement call routing? Try the TaskRouter Quickstart for an easy introduction.

Twilio's programmable voice <Queue> noun provides a simple mechanism to park calls on hold and place them in a named First-In, First-Out queue. By combining <Queue> with TaskRouter, <Queue> can be extended with richer routing models. Additionally, TaskRouter's agent availability model and Task reservation/acceptance flow can automatically push relevant work to agents as they become available.


Not familiar with TwiML voice applications? Take a moment to check out Twilio's TwiML API here.

Call Queue Default Limits

call-queue-default-limits page anchor

Voice tasks or calls are limited to 100 by default per queue.

Update the Call Queue Limit for Flex

update-the-call-queue-limit-for-flex page anchor

To find the call queue that corresponds with your Flex Task Assignment workflow, list your account's queue resources(link takes you to an external page) filtered by FriendlyName, or your workflow Sid (prefixed by WW). For example:


_10
curl 'https://api.twilio.com/2010-04-01/Accounts/ACxxx/Queues.json' -X GET \
_10
--data-urlencode 'FriendlyName=WWyyy' \
_10
-u ACxxx:[AuthToken]

Using a Queue Sid (prefixed by QU) from the Programmable Voice API response, you can change the maximum number of calls for that queue by updating the queue resource(link takes you to an external page) and specifying a different MaxSize. For example:


_10
curl 'https://api.twilio.com/2010-04-01/Accounts/ACxxx/Queues/QUzzz.json' -X POST \
_10
--data-urlencode 'FriendlyName=WWyyy' \
_10
--data-urlencode 'MaxSize=200' \
_10
-u ACxxx:[AuthToken]

Using TaskRouter with TwiML calls follows the basic flow:

  1. An incoming or outgoing Twilio voice phone call generates a webhook to your application server.
  2. Your application server generates a TwIML document containing <Enqueue> with attributes indicating which TaskRouter WorkflowSid should control call routing, and any Task attributes you would like to attach to the call.
  3. The call itself is placed on hold. TaskRouter executes a Workflow to find an eligible Worker to handle the call.
  4. If the caller hangs up before being assigned to a worker, the Task is automatically canceled.
  5. When a Worker is identified to handle the call, TaskRouter reserves the Worker and generates a webhook to your application.
  6. Your application responds specifying how the call should be bridged to the selected Worker, and optionally specifies the Activity to assign to the Worker once he or she has finished handling the call (for example "Wrapping up").
  7. Once the call is bridged to the Worker, the Task is marked as 'accepted'.
  8. When the call disconnects, the Worker is transitioned to the activity specified by your assignment instruction response.

Using <Enqueue> to route calls with TaskRouter

using-enqueue-to-route-calls-with-taskrouter page anchor

Below are some example TwiML documents that take advantage of TaskRouter for automatic call distribution.

Example #1: Simple TaskRouter Enqueue

example-1-simple-taskrouter-enqueue page anchor

To use Enqueue with TaskRouter, specify WorkflowSid when you generate the <Enqueue> statement in your TwiML document. Omit the named queue in the element body. The following example TwiML document will create a task in the provided Workflow and then put the caller into the default hold music:

Simple TaskRouter Enqueue

simple-taskrouter-enqueue page anchor
Node.js
Python
C#
Java
PHP
Ruby

_16
// Download the Node helper library from twilio.com/docs/node/install
_16
// These consts are your accountSid and authToken from https://www.twilio.com/console
_16
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_16
const express = require('express');
_16
const app = express();
_16
_16
app.post('/enqueue_call', (request, response) => {
_16
const resp = new VoiceResponse();
_16
resp.enqueue({ workflowSid: 'WW0123456789abcdef0123456789abcdef' });
_16
_16
response.setHeader('Content-Type', 'application/xml');
_16
response.write(resp.toString());
_16
response.end();
_16
});
_16
_16
app.listen(8080);

A task will be created in this Workflow with the call's standard parameters as attributes (call_sid, account_sid, to, from, etc).

Example #2: Attaching data to a call using Task

example-2-attaching-data-to-a-call-using-task page anchor

You may optionally also include a <Task> noun element to add additional attributes to the Task. <Task> must contain a valid JSON object as its body for the attributes of the Task. For example:

Attaching data to a call using Task

attaching-data-to-a-call-using-task page anchor
Node.js
Python
C#
Java
PHP
Ruby

_21
// Download the Node helper library from twilio.com/docs/node/install
_21
// These consts are your accountSid and authToken from https://www.twilio.com/console
_21
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_21
const express = require('express');
_21
const app = express();
_21
_21
app.post('/enqueue_call', (request, response) => {
_21
const resp = new VoiceResponse();
_21
_21
const json = { account_number: '12345abcdef' };
_21
_21
resp
_21
.enqueue('Friendly Name')
_21
.task({}, JSON.stringify(json));
_21
_21
response.setHeader('Content-Type', 'application/xml');
_21
response.write(resp.toString());
_21
response.end();
_21
});
_21
_21
app.listen(8080);

Example #3: Attaching priority and timeout to a call using Task

example-3-attaching-priority-and-timeout-to-a-call-using-task page anchor

You may optionally provide priority and/or timeout for a Task. This example provides a dynamic priority and timeout to a task as a property of the <Task> noun element. Priority and Timeout both must be valid integers. For example:

Attaching priority and timeout to a call using Task

attaching-priority-and-timeout-to-a-call-using-task page anchor
Node.js
Python
C#
Java
PHP
Ruby

_29
// Download the Node helper library from twilio.com/docs/node/install
_29
// These consts are your accountSid and authToken from https://www.twilio.com/console
_29
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_29
const express = require('express');
_29
const app = express();
_29
_29
app.post('/enqueue_call', (request, response) => {
_29
const resp = new VoiceResponse();
_29
_29
const json = { account_number: '12345abcdef' };
_29
_29
resp
_29
.enqueue({
_29
workflowSid: 'WW0123456789abcdef0123456789abcdef',
_29
})
_29
.task(
_29
{
_29
priority: '5',
_29
timeout: '200',
_29
},
_29
JSON.stringify(json)
_29
);
_29
_29
response.setHeader('Content-Type', 'application/xml');
_29
response.write(resp.toString());
_29
response.end();
_29
});
_29
_29
app.listen(8080);

Example #4: Specifying custom hold music and post-call treatment

example-4-specifying-custom-hold-music-and-post-call-treatment page anchor

This example uses the waitUrl property to provide custom hold music to the caller, and the action property to specify a post-call survey application that will be executed after the Worker and caller disconnect from one another. More information about the action property can be found here.

Specifying custom hold music and post-call treatment

specifying-custom-hold-music-and-post-call-treatment page anchor
Node.js
Python
C#
Java
PHP
Ruby

_25
// Download the Node helper library from twilio.com/docs/node/install
_25
// These consts are your accountSid and authToken from https://www.twilio.com/console
_25
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_25
const express = require('express');
_25
const app = express();
_25
_25
app.post('/enqueue_call', (request, response) => {
_25
const resp = new VoiceResponse();
_25
_25
const json = { account_number: '12345abcdef' };
_25
_25
resp
_25
.enqueue({
_25
workflowSid: 'WW0123456789abcdef0123456789abcdef',
_25
waitUrl: '/hold_music.php',
_25
action: '/post_bridge_survey.php',
_25
})
_25
.task({}, JSON.stringify(json));
_25
_25
response.setHeader('Content-Type', 'application/xml');
_25
response.write(resp.toString());
_25
response.end();
_25
});
_25
_25
app.listen(8080);

Note: TaskAttributes is legacy as of 8/15/15, but is still supported as a verb instead of Task.

Handling TaskRouter's Assignment Callback for voice calls: Bridging a call to a Worker

handling-taskrouters-assignment-callback-for-voice-calls-bridging-a-call-to-a-worker page anchor

Once a Worker has been reserved to handle a call, your application will receive an HTTP request at the AssignmentCallbackURL specified by the WorkflowSid you used in the <Enqueue> statement. Your application can respond with one of the following examples to control how the call is actually bridged to the Worker. Read about other options for handling the Assignment Callback here.

Automatically bridging call to Worker

automatically-bridging-call-to-worker page anchor

The 'dequeue' instruction removes the call from hold and bridges it to the selected Worker. To use the 'dequeue' instruction, your application should reply to the Assignment Callback request with a JSON document containing the following fields:


_10
{
_10
"instruction": "dequeue",
_10
"to": "{the Worker's phone number, sip uri, or client uri. Required.}",
_10
"from": "{the caller ID that you want to send to the Worker. Required.}",
_10
"post_work_activity_sid": "{the ActivitySid that should be assigned to the Worker after the call ends. Optional.}"
_10
}

More about these fields:

  • instruction specifies the assignment activity to perform. Use 'dequeue' to dequeue a call to a Worker. For a full list of assignment instructions, read about handling assignment callbacks here.
  • to specifies the Worker recipient's phone number.
  • from specifies the caller ID that should be sent when extending the call to the Worker.
  • post_work_activity_sid specifies the ActivitySid that you want to assign to the Worker after the call completes. Use this to transition your worker to a status that makes sense for their after-call, work for example "Wrapping up".

Upon issuing a Dequeue Instruction, TaskRouter will update the TaskAttributes of the Task with a worker_call_sid to denote the CallSid that is being created for the outgoing call to a given worker.

The TaskAttributes of the Task will then contain both the call_sid and worker_call_sid. Any event thereafter relating to the Task, such as task.completed, will have this information as well.

If you need Linked Call Tracking, consider listening to or querying for task.completed events that will have this information.

Bridging call after executing additional application logic

bridging-call-after-executing-additional-application-logic page anchor

Sometimes you may want your application to perform additional actions before bridging the call to the selected Worker. TaskRouter and TwiML have a few additional points of integration that make this possible. Here's how it typically works:

  1. Your application <Enqueue> s a call using TwiML, as described above. TaskRouter will reserve a Worker to handle the call and make an AssignmentCallback HTTP request to your application.
  2. Your application should respond to the request with an HTTP 200 response and an empty body. This tells TaskRouter you are processing the request, but not yet ready to accept the Reservation.
  3. Your application uses information from the AssignmentCallback request to perform some action, such as updating a CRM record.
  4. If the action you performed fails, or if the result is not your desired behavior, your application should tell TaskRouter to reject the Reservation.
  5. Once your application receives confirmation that the CRM update is complete, it makes a POST request to Twilio's /Calls REST API to place a call to the Worker's phone.
  6. When the Worker answers the call, Twilio makes an HTTP request to your application. Your application returns a TwiML document that <Dial> s <Queue> with the Tasks' reservationSid . For example:

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Dial>
_10
<Queue reservationSid="WR0123456789abcdef0123456789abcdef"/>
_10
</Dial>
_10
</Response>

Upon execution of this TwiML document, the Worker and the call will be bridged, and the pending Reservation will be marked as 'accepted'.

Note: If you plan to execute additional logic before bridging the waiting call with the Worker, make sure you set an appropriately high Task Reservation Timeout on your Workflow. The default is 120 seconds, which should be sufficient for most operations.

Providing additional parameters when <Dial>ing a ReservationSid

providing-additional-parameters-when-dialing-a-reservationsid page anchor

This example will accept the reservation and bridge to the task's call as in the previous example. When the call completes, the worker will be moved to the provided activity state ("wrapping up" for example).


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Dial>
_10
<Queue
_10
reservationSid="WR0123456789abcdef0123456789abcdef"
_10
postWorkActivitySid="WA0123456789abcdef0123456789abcdef"/>
_10
</Dial>
_10
</Response>


Important Restrictions and Considerations

important-restrictions-and-considerations page anchor

When combining TwiML and TaskRouter, there are a few important behaviors that you should know about.

TwiML will manage updates to associated TaskRouter Tasks

twiml-will-manage-updates-to-associated-taskrouter-tasks page anchor

When using <Enqueue> and <Dial><Queue reservationSid="..."></Dial> to create and manage Tasks, Twilio will keep the Task's lifecycle updated. For example, if the call disconnects before being answered by a Worker, TaskRouter will cancel the associated Task. Because of this linking, we recommend you do not modify the state of a Task that is linked to a waiting Twilio call.

Using the TaskRouter REST API to modify a Task's attributes can interfere with Twilio's ability to manage the Task's lifecycle. Additionally, Dial->Queue is responsible for accepting the reservation provided. If the reservation has been accepted already, either via the TaskRouter REST API or via an assignment instruction, the dequeue attempt will fail with an error.

Task attributes linking Tasks to calls

task-attributes-linking-tasks-to-calls page anchor

Each Task generated from TwiML contains a "call_sid" attribute, as well as the other standard Twilio call attributes ("to", "from", etc.).

Here is the full list of attributes,


_27
{
_27
"from_country": "",
_27
"called": "",
_27
"to_country": "",
_27
"to_city": "",
_27
"to_state": "",
_27
"caller_country": "",
_27
"call_status" : "",
_27
"call_sid" : "",
_27
"account_sid" : "",
_27
"from_zip" : "",
_27
"from" : "",
_27
"direction" : "",
_27
"called_zip" : "",
_27
"caller_state" : "",
_27
"to_zip" : "",
_27
"called_country" : "",
_27
"from_city" : "",
_27
"called_city" : "",
_27
"caller_zip" : "",
_27
"api_version" : "",
_27
"called_state" : "",
_27
"from_state" : "",
_27
"caller" : "",
_27
"caller_city" : "",
_27
"to" : ""
_27
}

Modifications to the Twilio Queues list

modifications-to-the-twilio-queues-list page anchor

When you use TaskRouter with <Enqueue>, TaskRouter will dynamically create voice Queues to hold your Tasks, using the provided WorkflowSid as a friendly name. These queues are used internally by the TaskRouter system to park the calls on hold. Modifying these queues or their members using the REST API may lead to unpredictable or undesirable results which prevent calls from being properly bridged.


Rate this page: