API Queue Inbound

Authentication chung: Tất cả API sử dụng Kong dual-auth: Header Authorization (API key) bắt buộc. Header X-Tenant-ID do Kong inject — nếu test internal không qua Kong thì bỏ header này, backend tự resolve tenantId theo Authorization key. Không dùng JWT (x-access-token) trong luồng này.

GET `/v1/queues/inbound`

Lấy danh sách tất cả queue inbound của tenant. Hỗ trợ phân trang.

Authentication: Header X-Api-Key (scope: queue). Kong dual-auth: ưu tiên X-Tenant-ID header, fallback query DB theo Authorization key.

Base URL: Dev: https://xapi-dev.alohub.vn | Prod: https://xapi.alohub.vn

Tham số

Tham số	Vị trí	Bắt buộc	Kiểu	Mô tả	Ví dụ
`page`	query	Không	`number`	Trang, bắt đầu từ 0 (default: 0)	0
`size`	query	Không	`number`	Số record/trang (default: 20)	20

Request Body

Code mẫu

curl -X GET "https://xapi.alohub.vn/v1/queues/inbound" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

# Phân trang
curl -X GET "https://xapi.alohub.vn/v1/queues/inbound?page=0&size=10" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.get(
  '{{host}}/api/v1/queues/inbound?page=0&size=20',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

params = {"page": "0", "size": "20"}
headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.get(
    '{{host}}/api/v1/queues/inbound',
    headers=headers, params=params
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "totalRecord": 3,
  "data": [
    {
      "callinId": 1001226,
      "callinName": "test",
      "strategy": 1,
      "musicinQueue": "waiting.wav",
      "timeWait": "120",
      "agentSelector": null,
      "nguongRanhRoi": null,
      "callinNumber": null
    }
  ]
}

Response Fields

Field	Kiểu	Mô tả
`success`	`string`	"1" = thành công
`totalRecord`	`number`	Tổng số queue
`data[].callinId`	`number`	ID queue — dùng làm {id} trong GET detail và PUT update
`data[].callinName`	`string`	Tên queue
`data[].strategy`	`number`	null	1=thường, 2=VIP, 3=blacklist, 4=divert, 99=tạm khoá
`data[].musicinQueue`	`string`	null	Tên file nhạc chờ (music on hold)
`data[].timeWait`	`string`	null	Thời gian chờ tối đa (giây)
`data[].agentSelector`	`string`	null	Thuật toán chọn agent
`data[].nguongRanhRoi`	`string`	null	Announce position: 0=tắt, 1=bật
`data[].callinNumber`	`string`	null	Số điện thoại của queue

Error Codes

HTTP	error_code	Mô tả	FE xử lý
401	UNAUTHORIZED	Thiếu hoặc sai API key	Redirect nhập lại key
403	INSUFFICIENT_SCOPE	Key không có scope `queue`	Hiện thông báo
404	NOT_FOUND	Không tìm thấy	Hiện thông báo
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn request	Retry sau Retry-After giây
500	FAIL	Lỗi hệ thống	Toast lỗi chung

Rate Limit Headers

Header	Mô tả
`X-RateLimit-Limit-Tenant`	Giới hạn tenant/10s
`X-RateLimit-Remaining-Tenant`	Còn lại tenant/10s
`X-RateLimit-Limit-Route`	Giới hạn route/10s
`X-RateLimit-Remaining-Route`	Còn lại route/10s
`Retry-After`	Giây cần chờ khi bị 429

GET `/v1/queues/inbound/{id}`

Lấy chi tiết 1 queue inbound. Backend kiểm tra ownership: queue phải thuộc tenant của auth header.

Authentication: Header X-Api-Key (scope: queue). Kong dual-auth: ưu tiên X-Tenant-ID header, fallback query DB theo Authorization key.

Base URL: Dev: https://xapi-dev.alohub.vn | Prod: https://xapi.alohub.vn

Tham số

Tham số	Vị trí	Bắt buộc	Kiểu	Mô tả	Ví dụ
`{id}`	path	Có	`number`	callinId (lấy từ GET /v1/queues/inbound)	1001226

Request Body

Code mẫu

curl -X GET "https://xapi.alohub.vn/v1/queues/inbound/1001226" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.get(
  '{{host}}/api/v1/queues/inbound/{{id}}',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.get(
    '{{host}}/api/v1/queues/inbound/{{id}}',
    headers=headers
)
print(response.json())

Response 200

{
  "callinId": 1001226,
  "callinName": "test",
  "strategy": 1,
  "musicinQueue": "waiting.wav",
  "timeWait": "120",
  "agentSelector": null,
  "nguongRanhRoi": null,
  "callinNumber": null
}

Response Fields

Field	Kiểu	Mô tả
`callinId`	`number`	ID queue
`callinName`	`string`	Tên queue
`strategy`	`number`	null	1=thường, 2=VIP, 3=blacklist, 4=divert, 99=tạm khoá
`musicinQueue`	`string`	null	Tên file nhạc chờ
`timeWait`	`string`	null	Thời gian chờ tối đa (giây)
`agentSelector`	`string`	null	Thuật toán chọn agent
`nguongRanhRoi`	`string`	null	Announce position: 0=tắt, 1=bật
`callinNumber`	`string`	null	Số điện thoại của queue

Error Codes

HTTP	error_code	Mô tả	FE xử lý
401	UNAUTHORIZED	Thiếu hoặc sai API key	Redirect nhập lại key
403	INSUFFICIENT_SCOPE	Key không có scope `queue`	Hiện thông báo
404	NOT_FOUND	Không tìm thấy	Hiện thông báo
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn request	Retry sau Retry-After giây
500	FAIL	Lỗi hệ thống	Toast lỗi chung

Rate Limit Headers

Header	Mô tả
`X-RateLimit-Limit-Tenant`	Giới hạn tenant/10s
`X-RateLimit-Remaining-Tenant`	Còn lại tenant/10s
`X-RateLimit-Limit-Route`	Giới hạn route/10s
`X-RateLimit-Remaining-Route`	Còn lại route/10s
`Retry-After`	Giây cần chờ khi bị 429

PUT `/v1/queues/inbound/{id}`

Cập nhật cấu hình queue inbound. Tất cả field optional — cần ít nhất 1 field. strategy phải là số nguyên trong tập {1,2,3,4,99}.

Authentication: Header X-Api-Key (scope: queue). Kong dual-auth: ưu tiên X-Tenant-ID header, fallback query DB theo Authorization key.

Base URL: Dev: https://xapi-dev.alohub.vn | Prod: https://xapi.alohub.vn

Tham số

Tham số	Vị trí	Bắt buộc	Kiểu	Mô tả	Ví dụ
`{id}`	path	Có	`number`	callinId	1001226

Request Body

{
  "moh_file_id": "waiting.wav",
  "max_wait_sec": "180",
  "strategy": 1,
  "announce_position": "1"
}

Field	Bắt buộc	Mô tả
`moh_file_id`	Không	Tên file nhạc chờ
`max_wait_sec`	Không	Thời gian chờ tối đa (string số, đơn vị giây)
`strategy`	Không	Loại quản lý: 1/2/3/4/99 — phải là số nguyên, dùng dropdown
`announce_position`	Không	"0" = tắt thông báo vị trí, "1" = bật

Code mẫu

curl -X PUT "https://xapi.alohub.vn/v1/queues/inbound/1001226" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"strategy":1}'

# Update nhiều field
curl -X PUT "https://xapi.alohub.vn/v1/queues/inbound/1001226" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"moh_file_id":"waiting.wav","max_wait_sec":"180","strategy":1}'

const axios = require('axios');
const response = await axios.put(
  '{{host}}/api/v1/queues/inbound/{{id}}',
  {
  "moh_file_id": "waiting.wav",
  "max_wait_sec": "180",
  "strategy": 1,
  "announce_position": "1"
},
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
payload = {
    "moh_file_id": "waiting.wav",
    "max_wait_sec": "180",
    "strategy": 1,
    "announce_position": "1"
}
response = requests.put(
    '{{host}}/api/v1/queues/inbound/{{id}}',
    json=payload,
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Inbound queue updated successfully"
}

Response Fields

Field	Kiểu	Mô tả
`success`	`string`	"1" = thành công
`error_code`	`string`	SUCCESS khi cập nhật thành công
`error_message`	`string`	Mô tả kết quả

Error Codes

HTTP	error_code	Mô tả	FE xử lý
401	UNAUTHORIZED	Thiếu hoặc sai API key	Redirect nhập lại key
403	INSUFFICIENT_SCOPE	Key không có scope `queue`	Hiện thông báo
400	INVALID_INPUT	Sai input	Hiện lỗi cụ thể
404	NOT_FOUND	Không tìm thấy	Hiện thông báo
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn request	Retry sau Retry-After giây
500	FAIL	Lỗi hệ thống	Toast lỗi chung

Rate Limit Headers

Header	Mô tả
`X-RateLimit-Limit-Tenant`	Giới hạn tenant/10s
`X-RateLimit-Remaining-Tenant`	Còn lại tenant/10s
`X-RateLimit-Limit-Route`	Giới hạn route/10s
`X-RateLimit-Remaining-Route`	Còn lại route/10s
`Retry-After`	Giây cần chờ khi bị 429

Quản lý hàng chờ gọi vào

API Queue Inbound

GET `/v1/queues/inbound`

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

GET `/v1/queues/inbound/{id}`

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

PUT `/v1/queues/inbound/{id}`

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

Related Articles

Quản lý hàng chờ gọi vào

API Queue Inbound

GET /v1/queues/inbound

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

GET /v1/queues/inbound/{id}

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

PUT /v1/queues/inbound/{id}

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

Related Articles

GET `/v1/queues/inbound`

GET `/v1/queues/inbound/{id}`

PUT `/v1/queues/inbound/{id}`