Skip to main content
Get startedGuidesTechnical Reference

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 bridge completes (when the agent or caller hangs up), execution continues with the SWML script specified in transfer_after_bridge.

enter_queue
objectrequired

An object that accepts the enter_queue parameters.

enter_queue Parameters​

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.transfer_after_bridge
stringrequired

SWML to execute after the bridge completes (when the agent or caller hangs up). This defines what should happen after the call is connected to an agent and the bridge ends.

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
integer
Default: 3600

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

Queue Status Callbacks​

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 queue and bridged
params.id
string

Unique queue entry identifier (UUID format).

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). Note: Present in enqueue and leave events. Not present 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 and bridged with another caller.

{
  "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",
    "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:
    • entering - Call is entering the queue
    • connecting - Call is in the process of connecting to an agent
    • connected - Successfully connected to an agent
    • leaving - Call is leaving the queue
    • 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. Set to -1 if not available.
  • entry_position: (out) The caller's position in the queue when they entered. Set to -1 if not available.
  • entry_size: (out) The total size of the queue when the caller entered. Set to -1 if not available.

Examples​

Basic Queue​

version: 1.0.0
sections:
  main:
    - enter_queue:
        queue_name: "my_queue"
        transfer_after_bridge: "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
        transfer_after_bridge: "https://example.com/post-call-swml"