Guides/Staffing a queue
App
Guides

Staffing a queue

Create a call queue, find the agents eligible to join it, and assign them with priority levels.

A queue holds inbound callers until an agent is free. A member is an agent attached to that queue with a priority level. This guide creates one queue and staffs it, using only endpoints that exist today.

You need a session and a workspace code first — see Authentication.

Every request below carries Cookie: sid=… and x-workspace-code. Writes also carry x-csrf-token. They are omitted from the samples after the first to keep them readable.

1 · Create the queue#

A queue needs a name, a status, and a distribution strategy. longest_idle_agent sends the call to whoever has been free longest.

bash
curl -X POST https://core.domain.test/v1/admin/queues \
  -H "Cookie: sid=$VOIGER_SESSION" \
  -H "x-workspace-code: let-s-eat" \
  -H "x-csrf-token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queue": {
      "name": "Sales",
      "status": "active",
      "strategy": "longest_idle_agent",
      "timeout": null,
      "timeout_action": { "type": "hangup" }
    }
  }'

The response carries the queue id you will use for every call below. Full field reference: Create Queue.

strategy currently accepts only longest_idle_agent. Sending anything else returns 400.

2 · Find who can join#

Not every agent is eligible — Get Queue Member Candidates returns the agents in this workspace who are not already members.

bash
curl https://core.domain.test/v1/admin/queues/{id}/members/candidates
json
{
  "candidates": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "first_name": "Salman",
      "last_name": "Ahmad"
    }
  ]
}

Calling this before assigning is what keeps you from a 409 on an agent who is already a member.

3 · Assign an agent#

Post a candidate's id with a priority level. Lower numbers are tried first, so level: 1 is your front line.

bash
curl -X POST https://core.domain.test/v1/admin/queues/{id}/members \
  -H "Content-Type: application/json" \
  -d '{
    "member": {
      "agent": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" },
      "level": 1
    }
  }'

To staff a queue in one shot, Add Queue Members takes an array instead — worth using when you are seeding a workspace, since it is one round trip rather than one per agent.

4 · Confirm the roster#

bash
curl https://core.domain.test/v1/admin/queues/{id}/members

Use Get Queue Members Count when you only need the number — a dashboard tile should not pull the whole list.

Tuning the roster#

Change someone's priority with Update Queue Member; levels can be reordered without removing anyone.
Remove an agent with Delete Queue Member. The agent keeps their other queues.
Agents see their own queues through Get Queues on the Agent API, which is workspace-scoped to them.

What this does not cover#

Routing calls *into* the queue is a separate concern — that is dialplan and IVR configuration, not queue membership. The queue built here is a destination; it starts receiving traffic once something points at it.

ESC