Queue

Manage Zorio PBX queues: CRUD queues, add / update / remove agent tiers.

GET /api/pbx/queues — List

Query: search (matches name or queue_number), page, per_page (1-200).

The response shape matches Extensions (5 keys: current_page, data, last_page, per_page, total).

GET /api/pbx/queues/{name} — Detail

Path parameter

name (user-facing string, NOT id).

Response body fields

Field	Type	Description	Valid values
name	string	User-facing queue name	unique per account
queue_number	string	Internal extension to dial into the queue	3-10 digits
team_id	integer|null	Owning team
strategy	string	Agent-selection strategy	ring-all / longest-idle-agent / round-robin / top-down / agent-with-least-talk-time / agent-with-fewest-calls / sequentially-by-agent-order / random
tier_rules_apply	bool	Whether tier rules are applied
tier_rule_wait_second	integer	Seconds to wait before escalating to the next tier	0-3600
tier_rule_wait_multiply_level	bool	Multiply wait seconds by the tier level
tier_rule_no_agent_no_wait	bool	Skip waiting if no agent is online in the tier
abandoned_resume_allowed	bool	Allow the caller to resume after hanging up
discard_abandoned_after	integer	Seconds before discarding an abandoned record
max_wait_time_with_no_agent	integer	Maximum wait while no agent is available (seconds)	≥ 0
max_wait_time_with_no_agent_time_reached	string	Action when the wait time expires	hangup / or another action name
time_base_score	string	Score by system (system-wide) or queue (within this queue only)	system / queue
recording_template	string|null	Recording filename template (Zorio PBX variable interpolation)
status	string	Status	active / inactive
created_at	datetime
updated_at	datetime

Response Body (JSON) — 200

{
  "data": {
    "name": "Support01",
    "queue_number": "200",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": true,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 14400,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}

POST /api/pbx/queues — Create

Request body fields

Field	Type	Required	Description	Values
name	string	✅	Queue name	max 100, unique per account
queue_number	string	✅	Number to dial into the queue	Regex ^[0-9]{3,10}$, unique per account
team_id	integer	optional	Owning team
strategy	string	optional	Agent-selection strategy	8 enum values (see Detail)
tier_rules_apply	bool	optional
tier_rule_wait_second	integer	optional		0-3600
tier_rule_wait_multiply_level	bool	optional
tier_rule_no_agent_no_wait	bool	optional
abandoned_resume_allowed	bool	optional
discard_abandoned_after	integer	optional		≥ 0
max_wait_time_with_no_agent	integer	optional		≥ 0
max_wait_time_with_no_agent_time_reached	string	optional
time_base_score	string	optional		system / queue

Request Body (JSON)

{
  "name": "Sales01",
  "queue_number": "300",
  "team_id": 2,
  "strategy": "agent-with-fewest-calls",
  "tier_rules_apply": true,
  "tier_rule_wait_second": 15,
  "tier_rule_no_agent_no_wait": true,
  "max_wait_time_with_no_agent": 60,
  "time_base_score": "queue"
}

Response Body (JSON) — 201

{
  "data": {
    "name": "Sales01",
    "queue_number": "300",
    "team_id": 2,
    "strategy": "agent-with-fewest-calls",
    "tier_rules_apply": true,
    "tier_rule_wait_second": 15,
    "tier_rule_wait_multiply_level": false,
    "tier_rule_no_agent_no_wait": true,
    "abandoned_resume_allowed": false,
    "discard_abandoned_after": 0,
    "max_wait_time_with_no_agent": 60,
    "max_wait_time_with_no_agent_time_reached": "hangup",
    "time_base_score": "queue",
    "recording_template": null,
    "status": "active"
  }
}

PUT / DELETE /api/pbx/queues/{name}

PUT

The body accepts every field from Create except name and queue_number (immutable).

{
  "strategy": "longest-idle-agent",
  "tier_rule_wait_second": 20,
  "max_wait_time_with_no_agent": 90
}

Response 200 = { data: { ...17 queue fields } }.

DELETE

Soft delete + the observer detaches the queue at runtime.

{ "data": { "deleted": true } }

Tier-agent management

GET /api/pbx/queues/{name}/agents — List tiers

Response body fields (each item in data[])

Field	Type	Description	Values
extension_number	string	Agent extension number
agent_name	string	Agent name <ext>@<sip-domain>
status	string	Agent presence status	available / available_on_demand / on_break / logged_out
state	string	Queue-runtime state	idle / waiting / receiving / in_a_queue_call
tier_level	integer	Priority level (1 = highest)	1-9
tier_position	integer	Order within the same level	1-99
max_no_answer	integer	Number of missed calls before auto-logout
wrap_up_time	integer	Wrap-up time after each call (seconds)

{
  "data": [
    {
      "extension_number": "2001",
      "agent_name": "2001@app.zorio.vn",
      "status": "available",
      "state": "idle",
      "tier_level": 1,
      "tier_position": 1,
      "max_no_answer": 3,
      "wrap_up_time": 5
    }
  ]
}

POST /api/pbx/queues/{name}/agents — Add a tier

Request body fields

Field	Type	Required	Description	Values
extension	string	✅	Extension number	Must exist. Regex ^[0-9]{3,10}$
tier_level	integer	optional	Priority level	1-9 (default 1)
tier_position	integer	optional	Position within the level	1-99 (default 1)

Automatically creates a tier-agent record if the agent does not exist. Returns 409 if the extension is already in this queue.

{ "extension": "2001", "tier_level": 1, "tier_position": 1 }

Response 201: { "data": { "added": true } }

PATCH /api/pbx/queues/{name}/agents/{ext} — Update a tier

Path: name (queue), ext (extension_number).

Request body fields (every field optional)

Field	Type	Description	Values
tier_level	integer	Priority level	1-9
tier_position	integer	Position within the level	1-99
status	string	Agent presence status	available / available_on_demand / on_break / logged_out

{ "tier_level": 2, "tier_position": 1, "status": "on_break" }

Response 200: { "data": { "updated": true } }

DELETE /api/pbx/queues/{name}/agents/{ext} — Remove a tier

No request body. Response 200: { "data": { "removed": true } }

Does NOT delete the tier-agent record — only removes it from this queue (the agent can still belong to other queues).