Voice

Enqueue

View as Markdown

The <Enqueue> verb places a call in a specified call queue. If the specified queue does not exist, a new queue will be created and the call will be placed into that new queue. Calls can be dequeued through the <Dial> verb or removed from the queue through the <Leave> verb.

Verb attributes

action
string

The action attribute takes an absolute URL. When a call leaves the queue, a request to this URL is made. If a call is dequeued through the <Leave> verb, the URL is immediately requested. If the call has been bridged to another party via the <Dial> verb, then the HTTP request is made only after both parties have disconnected. If action is not provided, SignalWire will continue reading the next verb in the document. See below for specified request parameters.

method
stringDefaults to POST

Specifies whether the redirect is a GET or a POST.

waitUrl
string

URL of the document to execute while the caller is in the queue. Default points to a playlist with classical music. waitUrl supports the following verbs: <Play>, <Say>, <Pause>, <Hangup>, <Redirect>, <Leave>, and <Gather>. See below for specified request parameters.

waitUrlMethod
stringDefaults to POST

Specifies whether the request to waitUrl is a GET or a POST.

Request parameters for the action URL

The action request contains the Standard Request Parameters as well as:

QueueResult
string

The result of the queued call. See below for all possible values.

QueueSid
string

The unique ID of the queue. Only available if a call is successfully placed into a queue.

QueueTime
string

The time a call was waiting in a queue. Only available if a call is successfully placed into a queue.

Values for parameter QueueResult

The parameter QueueResult has the following values:

ValueDescription
bridgedThe call was bridged and removed from the queue.
bridging-in-progressSignalWire is instructed to bridge the call.
errorAn error occurred either through the <Enqueue> verb or through the document retrieved from the waitUrl.
hangupThe caller hung up while still in the queue.
leaveThe caller left the queue through the <Leave> verb.
redirectedThe call was redirected out of the queue, through a REST API request, while the caller was in the queue.
redirected-from-bridgedThe queued and bridged session was transferred out.
queue-fullThe queue was full, so the placement into the queue was not accepted.
system-errorSignalWire had a malfunction while placing a call into a queue.

Request parameters for waitUrl

The waitUrl request contains the Standard Request Parameters as well as:

AvgQueueTime
integer

The average time, in seconds, that callers have been waiting in a queue.

CurrentQueueSize
integer

The current number of callers in a queue.

QueuePosition
integer

The current position in the queue.

QueueSid
string

The unique ID of the queue a caller is in.

QueueTime
integer

The time a call was waiting in a queue.

Nouns

The noun of an XML verb is nested within the verb upon which the verb acts. <Enqueue> has the following nouns:

NounDescription
plain textThe name of a specific queue.

Nesting

No other verbs can be nested within <Enqueue> and you cannot nest
<Enqueue> within any other verbs.

Examples

A simple enqueue

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Enqueue waitUrl="https://example.com/hold-music.xml">support</Enqueue>
4</Response>

While a caller is in the queue, SignalWire retrieves the XML document ‘hold-music.xml’ and executes it.

Playing wait music

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Play>http://your-application.com/classical.mp3</Play>
4</Response>

While callers in a queue are waiting, classical music is played.