Queues

When a call flow hits an <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.

Queue control uses a production API key (sk_live_) with the queues:write / queues:read scopes. Sandbox keys can’t manage queues.

Sign an agent in

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

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" }'

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" }),
});

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.

{ "agent": "agent_001", "queue": "support", "status": "logged_in" }

Sign an agent out

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

cURL

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" }'

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

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

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.

Putting it together

Your call flow enqueues the caller

An <Enqueue> verb names the queue, e.g. support.

Agents log in

Call the login endpoint for each available agent on support.

Callers ring logged-in agents

Wave rings them by your queue strategy (ring-all or round-robin).

You monitor the queue

Poll GET /v1/queues/members for a live view; queue KPI events also ride your event stream.

Get Started

Voice

Web Callback

Reference

Sign an agent in

Sign an agent out

See who’s waiting

Putting it together

Next steps

WaveML: Enqueue

How voice works

​Sign an agent in

​Sign an agent out

​See who’s waiting

​Putting it together

​Next steps

WaveML: Enqueue

How voice works

Sign an agent in

Sign an agent out

See who’s waiting

Putting it together

Next steps