Skip to navigation
Calling

enter_queue

View as MarkdownOpen in Claude

Place the current call in a named queue where it will wait to be connected to an available agent or resource. While waiting, callers will hear music or custom audio. When an agent connects to the queue (using the connect method), the caller and agent are bridged together after the optional whisper. After the bridge completes (when the agent or caller hangs up), execution continues with the SWML script specified in execute_after_queue, or the call hangs up if none was given.

Properties

enter_queue
objectRequired

An object that accepts the following properties.

enter_queue.queue_name
stringRequired

Name of the queue to enter. If a queue with this name does not exist, it will be automatically created.

enter_queue.execute_after_queue
string

SWML to execute after the bridge with the agent ends. When omitted, the call hangs up when the bridge ends. If the call leaves the queue without being bridged (wait_time expires or the caller hangs up), this field is not used and the script continues with the next instruction; check queue_result.

Can be either:

  • A URL (http or https) that returns a SWML document
  • An inline SWML document (as a JSON string)
enter_queue.status_url
string

HTTP or HTTPS URL to deliver queue status events. Status events will be sent via HTTP POST requests. See Queue Status Callbacks for event details.

enter_queue.wait_url
string

URL for media to play while waiting in the queue. The file will be fetched using an HTTP GET request. Supported audio formats include:

  • WAV (audio/wav, audio/wave, audio/x-wav)
  • MP3 (audio/mpeg)
  • AIFF (audio/aiff, audio/x-aifc, audio/x-aiff)
  • GSM (audio/x-gsm, audio/gsm)
  • μ-law (audio/ulaw)

Default hold music will be played if not set.

enter_queue.wait_time
integerDefaults to 180

Maximum time in seconds to wait in the queue before timeout.

enter_queue.whisper_url
string

SWML to run on the queued call when another call connects to the queue, before the two calls are bridged. See Whisper below.

Can be either:

  • A URL (http or https) that returns a SWML document
  • An inline SWML document (as a JSON string)

Whisper

A whisper runs SWML on the queued caller’s leg after another call connects to the queue with connect (for example, to: "queue:support"), but before the two calls hear each other. Use it to play the caller a short message, such as the name of the department they’re being connected to. Variables set during the whisper stay on the queued call, so the connecting call can’t read anything the whisper collects.

When the connecting call arrives, the hold audio stops and the whisper runs. SignalWire fetches a whisper_url URL with an HTTP POST, the same way it fetches any other SWML document. The connecting call is answered and hears silence while the whisper runs. When the whisper finishes, the two calls are bridged. If it’s still running after 60 seconds, the calls are bridged anyway.

If the queued caller hangs up during the whisper, or the whisper SWML hangs up the call, the calls are not bridged. The dequeue status event is sent when the connecting call arrives, before the whisper runs.

Queue Status Callbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

When you provide a status_url, SignalWire will send HTTP POST requests to that URL for the following queue events.

Event Object Structure

event_type
string

The type of event that is being reported. Will always be calling.call.queue for queue events.

event_channel
string

The SWML channel identifier for the call (format: swml:{uuid}).

timestamp
number

Unix timestamp with microsecond precision indicating when the event occurred.

project_id
string

The SignalWire project ID (UUID format).

space_id
string

The SignalWire Space ID (UUID format).

params
object

An object containing the event-specific parameters.

params.status
string

The event type identifier.

Possible Values:

  • enqueue - Caller added to queue
  • leave - Caller left without being bridged
  • dequeue - Caller pulled from the queue to be connected. Sent before the bridge is attempted, so it doesn’t confirm that the bridge succeeded
params.id
string

The queue identifier (UUID format). Every entry in the same queue has the same id; use call_id to identify the call.

params.name
string

The name of the queue.

params.position
integer

The caller’s position in the queue. Set to 0 when dequeued.

params.size
integer

The total number of callers in the queue. Set to 0 when dequeued.

params.avg_time
integer

Average wait time in the queue (in seconds).

params.enqueue_ts
integer

Unix timestamp in microseconds when the caller entered the queue. Set to 0 in dequeue events.

params.dequeue_ts
integer

Unix timestamp in microseconds when the caller was dequeued. Set to 0 in enqueue and leave events, populated in dequeue events.

params.leave_ts
integer

Unix timestamp in microseconds when the caller left the queue. Set to 0 in enqueue and dequeue events, populated in leave events.

params.status_url
string

The callback URL that was configured for status events.

params.control_id
string

Control identifier (UUID format). Present in enqueue and leave events. May be null in dequeue events.

params.call_id
string

The call identifier (UUID format).

params.node_id
string

The node identifier where the call is being processed (format: {uuid}@{region}).

Event Examples

enqueue Event

Sent when a caller is added to the queue.

{
"event_type": "calling.call.queue",
"event_channel": "swml:a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"timestamp": 1762966696.218623,
"project_id": "f8e7d6c5-b4a3-4210-9876-543210fedcba",
"space_id": "1a2b3c4d-5e6f-4789-abcd-ef0123456789",
"params": {
"status": "enqueue",
"id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
"name": "support_queue",
"position": 1,
"size": 1,
"avg_time": 0,
"enqueue_ts": 1762966696203260,
"dequeue_ts": 0,
"leave_ts": 0,
"status_url": "https://example.com/queue-status",
"control_id": "7a6b5c4d-3e2f-4123-8765-432109876543",
"call_id": "5d4c3b2a-1f0e-4321-9abc-def012345678",
"node_id": "2b3c4d5e-6f7a-4890-bcde-f01234567890@us-east"
}
}

leave Event

Sent when a caller leaves the queue without being bridged to another call (e.g., timeout, hangup).

{
"event_type": "calling.call.queue",
"event_channel": "swml:3c4d5e6f-7a8b-4910-cdef-012345678901",
"timestamp": 1762966720.978854,
"project_id": "f8e7d6c5-b4a3-4210-9876-543210fedcba",
"space_id": "1a2b3c4d-5e6f-4789-abcd-ef0123456789",
"params": {
"status": "leave",
"id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
"name": "support_queue",
"position": 1,
"size": 1,
"avg_time": 0,
"enqueue_ts": 1762966719450020,
"dequeue_ts": 0,
"leave_ts": 1762966720943789,
"status_url": "https://example.com/queue-status",
"control_id": "8b7a6c5d-4e3f-4234-9876-543210987654",
"call_id": "6e5d4c3b-2a1f-4432-abcd-ef0123456789",
"node_id": "4d5e6f7a-8b9c-4a01-def0-123456789012@us-east"
}
}

dequeue Event

Sent when a caller is pulled out of the queue to be connected with another call. It’s sent before the bridge is attempted, so it doesn’t confirm that the bridge succeeded.

{
"event_type": "calling.call.queue",
"event_channel": "swml:a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"timestamp": 1762966703.409084,
"project_id": "f8e7d6c5-b4a3-4210-9876-543210fedcba",
"space_id": "1a2b3c4d-5e6f-4789-abcd-ef0123456789",
"params": {
"status": "dequeue",
"id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
"name": "support_queue",
"position": 0,
"size": 0,
"avg_time": 0,
"enqueue_ts": 0,
"dequeue_ts": 1762966703217168,
"leave_ts": 0,
"status_url": "https://example.com/queue-status",
"control_id": null,
"call_id": "5d4c3b2a-1f0e-4321-9abc-def012345678",
"node_id": "2b3c4d5e-6f7a-4890-bcde-f01234567890@us-east"
}
}

Variables

Set by the method:

  • queue_result: (out) The result of the queue operation. Possible Values:
    • connected - Successfully connected to an agent
    • timeout - Waited too long and timed out
    • hangup - Caller hung up while waiting
    • failed - Queue operation failed due to an error
  • wait_time: (out) Time in seconds the caller waited in the queue, as a string. Set to -1 if not available.
  • entry_position: (out) The caller’s position in the queue when they entered, as a string. Set to -1 if not available.
  • entry_size: (out) The total size of the queue when the caller entered, as a string. Set to -1 if not available.

wait_time, entry_position, and entry_size are set only when the queue operation returns results. When queue_result is failed, they may be unset or still hold values from an earlier enter_queue, so check queue_result before using them.

Examples

Basic Queue

version: 1.0.0
sections:
main:
- enter_queue:
queue_name: "my_queue"
execute_after_queue: "https://example.com/post-call-swml"

Queue with Status Callback

version: 1.0.0
sections:
main:
- enter_queue:
queue_name: "sales_queue"
status_url: "https://example.com/queue-status"
wait_time: 1800
execute_after_queue: "https://example.com/post-call-swml"

Queue with whisper

When another call connects to support_queue, SignalWire fetches https://example.com/whisper-swml and runs the SWML document it returns on the queued caller’s leg before the bridge. The next example shows a typical whisper document.

version: 1.0.0
sections:
main:
- enter_queue:
queue_name: "support_queue"
whisper_url: "https://example.com/whisper-swml"

Queue with an inline whisper

This example passes the whisper document inline as a JSON string. When another call connects to support_queue, the queued caller hears “You are being connected to support.” and then the two calls are bridged. To host it instead, return the same document from the URL you set in whisper_url.

version: 1.0.0
sections:
main:
- enter_queue:
queue_name: "support_queue"
whisper_url: '{"version":"1.0.0","sections":{"main":[{"play":{"url":"say:You are being connected to support."}}]}}'