Hàng đợi (Queue)

Quản lý hàng đợi của Zorio PBX: CRUD queue, thêm/sửa/xoá tier agent.

GET /api/pbx/queues — Liệt kê

Query: search (match name hoặc queue_number), page, per_page (1-200).

Response format giống Extensions (5 keys: current_page, data, last_page, per_page, total).

GET /api/pbx/queues/{name} — Chi tiết

Path parameter

name (string user-facing, KHÔNG phải id).

Response body fields

Field	Type	Mô tả	Giá trị hợp lệ
name	string	Tên queue user-facing	unique per tài khoản
queue_number	string	Số extension nội bộ để dial vào queue	3-10 chữ số
team_id	integer|null	Nhóm sở hữu
strategy	string	Cách chọn agent	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	Áp dụng tier rule không
tier_rule_wait_second	integer	Số giây chờ trước khi escalate lên tier kế tiếp	0-3600
tier_rule_wait_multiply_level	bool	Nhân số giây theo tier level
tier_rule_no_agent_no_wait	bool	Không chờ nếu tier không có agent online
abandoned_resume_allowed	bool	Cho phép caller gọi lại sau khi cúp
discard_abandoned_after	integer	Sau bao nhiêu giây mới xoá record abandoned
max_wait_time_with_no_agent	integer	Tối đa chờ khi không có agent (giây)	≥ 0
max_wait_time_with_no_agent_time_reached	string	Hành động khi hết thời gian chờ	hangup / hoặc tên action khác
time_base_score	string	Tính điểm theo system (toàn hệ) hay queue (chỉ trong queue)	system / queue
recording_template	string|null	Template tên file ghi âm (Zorio PBX variable interpolation)
status	string	Trạng thái	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 — Tạo mới

Request body fields

Field	Type	Required	Mô tả	Giá trị
name	string	✅	Tên queue	max 100, unique per tài khoản
queue_number	string	✅	Số dial vào queue	Regex ^[0-9]{3,10}$, unique per tài khoản
team_id	integer	optional	Nhóm sở hữu
strategy	string	optional	Cách chọn agent	8 giá trị enum (xem Chi tiết)
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

Body chấp nhận mọi field như Create trừ name và queue_number (immutable).

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

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

DELETE

Soft delete + observer tự detach runtime.

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

Quản lý tier agent

GET /api/pbx/queues/{name}/agents — Liệt kê tier

Response body fields (mỗi item trong data[])

Field	Type	Mô tả	Giá trị
extension_number	string	Số máy nhánh agent
agent_name	string	Tên agent <ext>@<sip-domain>
status	string	Trạng thái presence agent	available / available_on_demand / on_break / logged_out
state	string	State runtime hàng đợi	idle / waiting / receiving / in_a_queue_call
tier_level	integer	Cấp ưu tiên (1 = cao nhất)	1-9
tier_position	integer	Thứ tự trong cùng level	1-99
max_no_answer	integer	Số lần ko nhấc trước khi auto logout
wrap_up_time	integer	Thời gian wrap-up sau cuộc (giây)

{
  "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 — Thêm tier

Request body fields

Field	Type	Required	Mô tả	Giá trị
extension	string	✅	Số máy nhánh	Phải tồn tại. Regex ^[0-9]{3,10}$
tier_level	integer	optional	Cấp ưu tiên	1-9 (default 1)
tier_position	integer	optional	Vị trí trong level	1-99 (default 1)

Auto tạo record tier agent nếu agent chưa tồn tại. Trả 409 nếu ext đã ở trong queue này.

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

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

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

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

Request body fields (mọi field optional)

Field	Type	Mô tả	Giá trị
tier_level	integer	Cấp ưu tiên	1-9
tier_position	integer	Vị trí trong level	1-99
status	string	Trạng thái presence agent	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} — Xoá tier

Không có Request Body. Response 200: { "data": { "removed": true } }

KHÔNG xoá tier agent record — chỉ remove khỏi queue (agent có thể tham gia queue khác).