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

TwiML™ Voice: <Enqueue>


The <Enqueue> verb enqueues the current call in a call queue. Enqueued calls wait in hold music until the call is dequeued by another caller via the <Dial> verb or transferred out of the queue via the REST API or the <Leave> verb.

The <Enqueue> verb will create a queue on demand, if the queue does not already exist. The default maximum length of the queue is 100. This can be modified using the REST API.

<Enqueue> allows you to specify a named queue that already exists by placing the queue name between <Enqueue>'s opening and closing tags. The queue name must be 64 characters or less in length. If the named queue hasn't yet been created, Twilio will create one with the queue name included within <Enqueue>'s opening and closing tags.


Verb Attributes

attributes page anchor

The <Enqueue> verb supports the following attributes that modify its behavior:

Attribute NameAllowed ValuesDefault Value
actionrelative or absolute URLnone
methodGET, POSTPOST
waitUrlrelative or absolute URLdefault classical playlist(link takes you to an external page)
waitUrlMethodGET, POSTPOST
workflowSidTaskRouter Workflow Sidnone

action

attributes-action page anchor

The action attribute takes an absolute or relative URL as a value. A request is made to this URL when the call leaves the queue, describing the dequeue reason and details about the time spent in the queue, which are described below. In the case where a call is dequeued due to a REST API request or the <Leave> verb, the action URL is requested right away. In the case where a call is dequeued via the <Dial> verb, the action URL is hit once when the bridged parties disconnect. If no action is provided, Twilio will fall through to the next verb in the document, if any.

Request Parameters

attributes-action-parameters page anchor

Twilio passes the following parameters in addition to the standard TwiML Voice request parameters with its request to the action URL:

ParameterDescription
QueueResultThe final result of the enqueued call. See queue result values below for details.
QueueSidThe SID of the queue. This is only available if the call was actually enqueued.
QueueTimeThe time the call spent in the queue. This is only available if the call was actually enqueued.

The following values represent the result of an attempt to enqueue a caller.

ValueDescription
bridgedThe call was dequeued and bridged to the dequeuer.
bridging-in-processTwilio has been instructed to bridge the enqueued party.
errorThe TwiML contained an error, either in the <Enqueue> verb itself or in the TwiML retrieved from a waitUrl. Check the App Monitor.
hangupThe enqueued caller hung up before connecting to a dequeued call.
leaveThe enqueued caller exited the queue via the <Leave> verb.
redirectedWhile in the queue, the call was redirected out of the queue, typically by a REST API request.
redirected-from-bridgedThe queued and then successfully bridged session was transferred out.
queue-fullThe targeted queue was full, thus the enqueue attempt was rejected.
system-errorThe Twilio system malfunctioned during the enqueue process. This can happen if a caller hangs up before being fully enqueued.

The method attribute specifies the HTTP method Twilio uses when sending a request to the action URL. takes the value GET or POST. POST is the default value.

The waitUrl attribute specifies a URL pointing to a TwiML document containing TwiML verbs that will be executed while the caller is waiting in the queue.

Once TwiML document located at the waitUrl runs out of verbs to execute, Twilio re-requests the waitUrl. This loops the hold music indefinitely. The <Redirect> verb can be used for multiple TwiML document call flows, but a call will always return to the waitUrl once there is no TwiML left to execute.

The following verbs are supported in the TwiML document located at the waitUrl:

VerbDescription
<Play>Plays a file to the caller.
<Say>Say something to the caller using Twilio text-to-speech.
<Pause>Pauses for a specified duration.
<Hangup>Hangs up the call and thereby leaving the queue and ending the call.
<Redirect>Redirect to another TwiML document.
<Leave>Makes the current call leave the queue, but doesn't hang up the call. Execution proceeds with the next verb after the '<Enqueue>' verb.
<Gather>Collects digits that a caller enters into his or her telephone keypad. NOTE: The only valid value for <Gather>'s input attribute is dtmf when <Gather> is returned in an <Enqueue> waitUrl; the speech value for the input attribute is not accepted.

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'waitUrl' URL:

ParameterDescription
QueuePositionThe current queue position for the enqueued call.
QueueSidThe SID of the Queue that the caller is in.
QueueTimeThe time in seconds that the caller has been in the queue.
AvgQueueTimeAn average of how long the current enqueued callers have been in the queue in seconds.
CurrentQueueSizeThe current number of enqueued calls in this queue.
MaxQueueSizeThe maximum number of enqueued calls for this queue.

The waitUrlMethod attribute specifies the HTTP method Twilio uses when making a request to the waituUrl. Allowed values are GET or POST. The default value is POST.

The workflowSid attribute tells Twilio to create a new TaskRouter Task to represent this call and specifies the ID of the desired Workflow to handle it.

If workflowSid is specified, it is not necessary to specify a name for the Queue to place the call in. When a Worker is identified to handle the call it can be dequeued and connected using the dequeue assignment instruction.


The "noun" of a TwiML verb is the nested content of the verb that's not a verb itself; it's the information the verb acts upon. These are the nouns for <Enqueue>:

NounDescription
<Task>The attributes to be set for the newly created task, formatted as JSON

You can find more information and examples on how to use <Task> on the TaskRouter TwiML Integration page.


Example 1: Simple Enqueue

examples-1 page anchor

This TwiML document tells Twilio to fetch the wait-music.xml TwiML document and execute it while the caller is in the queue:

Node.js
Python
C#
Java
PHP
Ruby

_10
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10
_10
const response = new VoiceResponse();
_10
response.enqueue({
_10
waitUrl: 'wait-music.xml'
_10
}, 'support');
_10
_10
console.log(response.toString());

Output

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Enqueue waitUrl="wait-music.xml">support</Enqueue>
_10
</Response>

The wait-music.xml TwiML document plays some nice hold music:

Node.js
Python
C#
Java
PHP
Ruby

_10
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10
_10
const response = new VoiceResponse();
_10
response.play('http://com.twilio.sounds.music.s3.amazonaws.com/MARKOVICHAMP-Borghestral.mp3');
_10
_10
console.log(response.toString());

Output

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Play>http://com.twilio.sounds.music.s3.amazonaws.com/MARKOVICHAMP-Borghestral.mp3</Play>
_10
</Response>


Hints and Advanced Uses

hints page anchor
  • You can use the parameters on the waitUrl request to <Say> back to the caller what his or her queue position is and how long he or she can expect to wait.

Rate this page: