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

# Queues

> Route callers to agents with call-center queues, and manage who's logged in.

When a call flow hits an [`<Enqueue>`](/voice/waveml#enqueue) verb, the caller
waits in a named queue and rings the agents who are **logged into it**. Queues are
created on demand — there's nothing to provision. This API signs agents in and
out and shows you who's waiting.

<Note>
  Queue control uses a **production** API key (`sk_live_`) with the
  `queues:write` / `queues:read` scopes. Sandbox keys can't manage queues.
</Note>

## Sign an agent in

`POST /v1/queues/agents/login` — the agent starts ringing for calls in that queue.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wave.sa/v1/queues/agents/login \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "agent": "agent_001", "queue": "support" }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.wave.sa/v1/queues/agents/login", {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent: "agent_001", queue: "support" }),
  });
  ```
</CodeGroup>

| Field   | Type   | Required | Notes                                                  |
| ------- | ------ | -------- | ------------------------------------------------------ |
| `agent` | string | **yes**  | `A–Z a–z 0–9 _ -`, ≤64 chars.                          |
| `queue` | string | **yes**  | Same charset, ≤64 chars. Matches the `<Enqueue>` name. |

```json theme={null}
{ "agent": "agent_001", "queue": "support", "status": "logged_in" }
```

## Sign an agent out

`POST /v1/queues/agents/logout` signs the agent out of **all** queues.

```bash cURL theme={null}
curl -X POST https://api.wave.sa/v1/queues/agents/logout \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "agent_001" }'
```

```json theme={null}
{ "agent": "agent_001", "queue": null, "status": "logged_out" }
```

## See who's waiting

`GET /v1/queues/members?queue=support` returns a live snapshot of the callers in a
queue.

```json theme={null}
{
  "queue": "support",
  "count": 2,
  "members": [
    {
      "position": 1,
      "channel_uuid": "27d6dd39-…",
      "src_number": "+966501112222",
      "state": "waiting",
      "wait_seconds": 45,
      "agent": null
    }
  ]
}
```

| Field          | Meaning                                                 |
| -------------- | ------------------------------------------------------- |
| `position`     | Place in line (1 = next).                               |
| `state`        | `waiting` or `talking`.                                 |
| `wait_seconds` | How long this caller has waited.                        |
| `agent`        | The agent handling the caller, or `null` while waiting. |

<Warning>
  Queue control talks to the live voice engine. If the engine is unreachable you'll
  get `QUEUE_SERVICE_UNAVAILABLE` (503) or `QUEUE_CONTROL_FAILED` (502) — retry with
  backoff.
</Warning>

## Putting it together

<Steps>
  <Step title="Your call flow enqueues the caller">
    An [`<Enqueue>`](/voice/waveml#enqueue) verb names the queue, e.g. `support`.
  </Step>

  <Step title="Agents log in">
    Call the login endpoint for each available agent on `support`.
  </Step>

  <Step title="Callers ring logged-in agents">
    Wave rings them by your queue strategy (`ring-all` or `round-robin`).
  </Step>

  <Step title="You monitor the queue">
    Poll `GET /v1/queues/members` for a live view; queue KPI events also ride your
    [event stream](/voice/overview#events-you-can-subscribe-to).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="WaveML: Enqueue" icon="code" href="/voice/waveml#enqueue">
    The verb that puts a caller in a queue.
  </Card>

  <Card title="How voice works" icon="phone-volume" href="/voice/overview">
    Where queues sit in the call lifecycle.
  </Card>
</CardGroup>