> ## Documentation Index
> Fetch the complete documentation index at: https://withkazi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Queues: Routing Inbound Calls to Agents

> Call queues in LaraCopilot distribute incoming calls across a pool of extension-based agents using configurable routing strategies.

A **call queue** in LaraCopilot holds inbound callers in a virtual waiting line and distributes them to available agents according to a routing strategy. Queues decouple the point where a call arrives (a DID number) from the people who answer it (extensions enrolled as agents), making it straightforward to scale agent pools up or down without changing how numbers are published. Each queue belongs to a single tenant and is identified by a short `queue_number` that the PBX uses internally.

## Key fields

| Field          | Type    | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `tenant_id`    | integer | The tenant that owns this queue. Required.                                 |
| `name`         | string  | Human-readable label for the queue (e.g. `Support Tier 1`).                |
| `queue_number` | string  | Short internal number identifying the queue in the PBX. Max 20 characters. |
| `strategy`     | string  | Call distribution algorithm (e.g. `ringall`, `leastrecent`, `roundrobin`). |
| `timeout`      | integer | Seconds to ring an agent before moving to the next one. Minimum 1.         |
| `status`       | string  | Operational state of the queue (e.g. `active`, `inactive`).                |

## Queue agents

Agents are extensions that have been enrolled in a queue. Each queue tracks its enrolled agents, and the `agents` array returned by the API lists all extensions currently assigned to that queue.

<Warning>
  Removing an extension from the system does not automatically unenroll it from queues. Remove the extension from any queues it belongs to before deleting it to prevent routing errors.
</Warning>

Agents are selected according to the queue's `strategy`. Common values include:

* **`ringall`** — all available agents ring simultaneously; first to answer wins.
* **`leastrecent`** — the agent who answered a call least recently is tried first.
* **`roundrobin`** — agents are cycled through in order, one call at a time.

## API examples

### Create a queue

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-instance/api/queues \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": 1,
      "name": "Support Tier 1",
      "queue_number": "800",
      "strategy": "leastrecent",
      "timeout": 30,
      "status": "active"
    }'
  ```

  ```json Response (201) theme={null}
  {
    "message": "Queue created successfully.",
    "data": {
      "id": 5,
      "tenant_id": 1,
      "name": "Support Tier 1",
      "queue_number": "800",
      "strategy": "leastrecent",
      "timeout": 30,
      "status": "active",
      "created_at": "2026-04-22T10:15:00Z",
      "updated_at": "2026-04-22T10:15:00Z"
    }
  }
  ```
</CodeGroup>

### Retrieve a queue with its agents

<CodeGroup>
  ```bash cURL theme={null}
  curl https://your-instance/api/queues/5
  ```

  ```json Response (200) theme={null}
  {
    "message": "Queue loaded successfully.",
    "data": {
      "id": 5,
      "tenant_id": 1,
      "name": "Support Tier 1",
      "queue_number": "800",
      "strategy": "leastrecent",
      "timeout": 30,
      "status": "active",
      "tenant": { "id": 1, "name": "Acme Corp" },
      "agents": []
    }
  }
  ```
</CodeGroup>

<Tip>
  Pair each inbound DID with a call queue for production traffic. Assign the DID a `DidRoute` that targets the queue, so callers always reach an available agent rather than a single extension that may be busy or offline.
</Tip>