Queueing Twilio calls with TaskRouter

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.

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

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

1
curl 'https://api.twilio.com/2010-04-01/Accounts/ACxxx/Queues.json' -X GET \
2
--data-urlencode 'FriendlyName=WWyyy' \
3
-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 and specifying a different MaxSize. For example:

1
curl 'https://api.twilio.com/2010-04-01/Accounts/ACxxx/Queues/QUzzz.json' -X POST \
2
--data-urlencode 'FriendlyName=WWyyy' \
3
--data-urlencode 'MaxSize=200' \
4
-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 they have 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.

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

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:

1
// Download the Node helper library from twilio.com/docs/node/install
2
// These consts are your accountSid and authToken from https://www.twilio.com/console
3
const VoiceResponse = require('twilio').twiml.VoiceResponse;
4
const express = require('express');
5
const app = express();
6

7
app.post('/enqueue_call', (request, response) => {
8
  const resp = new VoiceResponse();
9
  resp.enqueue({ workflowSid: 'WW0123456789abcdef0123456789abcdef' });
10

11
  response.setHeader('Content-Type', 'application/xml');
12
  response.write(resp.toString());
13
  response.end();
14
});
15

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).

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:

1
// Download the Node helper library from twilio.com/docs/node/install
2
// These consts are your accountSid and authToken from https://www.twilio.com/console
3
const VoiceResponse = require('twilio').twiml.VoiceResponse;
4
const express = require('express');
5
const app = express();
6

7
app.post('/enqueue_call', (request, response) => {
8
  const resp = new VoiceResponse();
9

10
  const json = { account_number: '12345abcdef' };
11

12
  resp
13
    .enqueue('Friendly Name')
14
    .task({}, JSON.stringify(json));
15

16
  response.setHeader('Content-Type', 'application/xml');
17
  response.write(resp.toString());
18
  response.end();
19
});
20

21
app.listen(8080);

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:

1
// Download the Node helper library from twilio.com/docs/node/install
2
// These consts are your accountSid and authToken from https://www.twilio.com/console
3
const VoiceResponse = require('twilio').twiml.VoiceResponse;
4
const express = require('express');
5
const app = express();
6

7
app.post('/enqueue_call', (request, response) => {
8
  const resp = new VoiceResponse();
9

10
  const json = { account_number: '12345abcdef' };
11

12
  resp
13
    .enqueue({
14
      workflowSid: 'WW0123456789abcdef0123456789abcdef',
15
    })
16
    .task(
17
      {
18
        priority: '5',
19
        timeout: '200',
20
      },
21
      JSON.stringify(json)
22
    );
23

24
  response.setHeader('Content-Type', 'application/xml');
25
  response.write(resp.toString());
26
  response.end();
27
});
28

29
app.listen(8080);

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.

1
// Download the Node helper library from twilio.com/docs/node/install
2
// These consts are your accountSid and authToken from https://www.twilio.com/console
3
const VoiceResponse = require('twilio').twiml.VoiceResponse;
4
const express = require('express');
5
const app = express();
6

7
app.post('/enqueue_call', (request, response) => {
8
  const resp = new VoiceResponse();
9

10
  const json = { account_number: '12345abcdef' };
11

12
  resp
13
    .enqueue({
14
      workflowSid: 'WW0123456789abcdef0123456789abcdef',
15
      waitUrl: '/hold_music.php',
16
      action: '/post_bridge_survey.php',
17
    })
18
    .task({}, JSON.stringify(json));
19

20
  response.setHeader('Content-Type', 'application/xml');
21
  response.write(resp.toString());
22
  response.end();
23
});
24

25
app.listen(8080);

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

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.

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:

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

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.

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:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Dial>
4
    <Queue reservationSid="WR0123456789abcdef0123456789abcdef"/>
5
  </Dial>
6
</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.

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).

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Dial>
4
    <Queue
5
      reservationSid="WR0123456789abcdef0123456789abcdef"
6
      postWorkActivitySid="WA0123456789abcdef0123456789abcdef"/>
7
  </Dial>
8
</Response>

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

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.

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,

1
{
2
  "from_country": "",
3
  "called": "",
4
  "to_country": "",
5
  "to_city": "",
6
  "to_state": "",
7
  "caller_country": "",
8
  "call_status" : "",
9
  "call_sid" : "",
10
  "account_sid" : "",
11
  "from_zip" : "",
12
  "from" : "",
13
  "direction" : "",
14
  "called_zip" : "",
15
  "caller_state" : "",
16
  "to_zip" : "",
17
  "called_country" : "",
18
  "from_city" : "",
19
  "called_city" : "",
20
  "caller_zip" : "",
21
  "api_version" : "",
22
  "called_state" : "",
23
  "from_state" : "",
24
  "caller" : "",
25
  "caller_city" : "",
26
  "to" : ""
27
}

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.