enter_queue
enter_queue
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
An object that accepts the following properties.
enter_queue.queue_name
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
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
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
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
Maximum time in seconds to wait in the queue before timeout.
enter_queue.whisper_url
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 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
The type of event that is being reported. Will always be calling.call.queue for queue events.
event_channel
The SWML channel identifier for the call (format: swml:{uuid}).
timestamp
Unix timestamp with microsecond precision indicating when the event occurred.
project_id
The SignalWire project ID (UUID format).
space_id
The SignalWire Space ID (UUID format).
params
An object containing the event-specific parameters.
params.status
The event type identifier.
Possible Values:
enqueue- Caller added to queueleave- Caller left without being bridgeddequeue- 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
The queue identifier (UUID format). Every entry in the same queue has the same id; use call_id to identify the call.
params.name
The name of the queue.
params.position
The caller’s position in the queue. Set to 0 when dequeued.
params.size
The total number of callers in the queue. Set to 0 when dequeued.
params.avg_time
Average wait time in the queue (in seconds).
params.enqueue_ts
Unix timestamp in microseconds when the caller entered the queue. Set to 0 in dequeue events.
params.dequeue_ts
Unix timestamp in microseconds when the caller was dequeued. Set to 0 in enqueue and leave events, populated in dequeue events.
params.leave_ts
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
The callback URL that was configured for status events.
params.control_id
Control identifier (UUID format). Present in enqueue and leave events. May be null in dequeue events.
params.call_id
The call identifier (UUID format).
params.node_id
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.
leave Event
Sent when a caller leaves the queue without being bridged to another call (e.g., timeout, hangup).
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.
Variables
Set by the method:
- queue_result: (out) The result of the queue operation. Possible Values:
connected- Successfully connected to an agenttimeout- Waited too long and timed outhangup- Caller hung up while waitingfailed- Queue operation failed due to an error
- wait_time: (out) Time in seconds the caller waited in the queue, as a string. Set to
-1if not available. - entry_position: (out) The caller’s position in the queue when they entered, as a string. Set to
-1if not available. - entry_size: (out) The total size of the queue when the caller entered, as a string. Set to
-1if 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
Queue with Status Callback
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.
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.