> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# enter_queue

> Place the call in a 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`](/docs/swml/reference/calling/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 `execute_after_queue`, or the call hangs up if none was given.

## **Properties**

**`enter_queue`** `object` — required

An object that accepts the following properties.

---

**`enter_queue.queue_name`** `string` — required

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](#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: 180

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

---

## **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](/docs/platform/webhooks#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 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). 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.

```json
{
  "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).

```json
{
  "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.

```json
{
  "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**:
  * `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

#### YAML

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

#### JSON

```json
{
  "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

#### YAML

```yaml
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"
```

#### JSON

```json
{
  "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"
        }
      }
    ]
  }
}
```

> Place the call in a queue.