API Quản lý Agent

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/agents`

Lấy danh sách tất cả agent của tenant. Hỗ trợ filter theo status, queue và phân trang.

Authentication: Header X-Api-Key (scope: agent). 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ụ
`team_id`	query	Không	`number`	Filter theo tenantId cụ thể (mặc định từ auth)	20260310
`status`	query	Không	`number`	1 = active, 0 = inactive	1
`queue_id`	query	Không	`number`	Filter agents thuộc callin queue này	1001226
`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/agents" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

# Filter active + queue
curl -X GET "https://xapi.alohub.vn/v1/agents?status=1&queue_id=1001226&page=0&size=20" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

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

import requests

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

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "SUCCESS",
  "totalRecord": 413,
  "data": [
    {
      "tenantId": 20260310,
      "tenantName": "AloHub",
      "agentId": "082018",
      "status": 1,
      "userName": "AloHub.admin",
      "queueCallin": "1001226-test",
      "queueCallout": 13876,
      "queueCalloutName": "AloHub",
      "queueCallinId": "1001226",
      "isFollowMe": 1,
      "priority": "1",
      "systemStatus": "AVAILABLE",
      "userStatus": "LOGOUT"
    }
  ]
}

Response Fields

Field	Kiểu	Mô tả
`success`	`string`	"1" = thành công, "0" = lỗi
`error_code`	`string`	Mã lỗi
`totalRecord`	`number`	Tổng số agent
`data[].tenantId`	`number`	ID tenant
`data[].tenantName`	`string`	Tên tenant
`data[].agentId`	`string`	Extension number — dùng làm {id} trong PUT /queues và PUT /recording
`data[].status`	`number`	1 = active, 0 = inactive
`data[].userName`	`string`	null	Tên đăng nhập
`data[].queueCallin`	`string`	null	"-" — callin queue đang gắn
`data[].queueCallinId`	`string`	null	ID callin queue
`data[].queueCallout`	`number`	null	ID callout queue
`data[].queueCalloutName`	`string`	null	Tên callout queue
`data[].isFollowMe`	`number`	null	1 = bật follow-me
`data[].priority`	`string`	null	Độ ưu tiên trong queue
`data[].systemStatus`	`string`	null	AVAILABLE / NOT AVAILABLE
`data[].userStatus`	`string`	null	AVAILABLE / LOGOUT

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 `agent`	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/agents/{id}/queues`

Gán agent vào callin hoặc callout queue. type=callin: REPLACE HOÀN TOÀN danh sách queue cũ — muốn thêm 1 queue cần gửi cả danh sách cũ + mới.

Authentication: Header X-Api-Key (scope: agent). 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`	agentId = extension number (lấy từ GET /v1/agents)	082018
`type`	query	Không	`string`	"callin" (default) hoặc "callout"	callin

Request Body

{
  "queue_ids": [
    1001226,
    1000886
  ],
  "priority": 1
}

Field	Bắt buộc	Mô tả
`queue_ids`	Có	Mảng queue ID. Không được rỗng.
`priority`	Không	Độ ưu tiên trong callin queue. Chỉ áp dụng type=callin.

Code mẫu

curl -X PUT "https://xapi.alohub.vn/v1/agents/082018/queues?type=callin" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"queue_ids":[1001226,1000886],"priority":1}'

# Gán callout queue
curl -X PUT "https://xapi.alohub.vn/v1/agents/082018/queues?type=callout" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"queue_ids":[13876]}'

const axios = require('axios');
const response = await axios.put(
  '{{host}}/api/v1/agents/{{id}}/queues?type=callin',
  {
  "queue_ids": [
    1001226,
    1000886
  ],
  "priority": 1
},
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

params = {"type": "callin"}
headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
payload = {
    "queue_ids": [
        1001226,
        1000886
    ],
    "priority": 1
}
response = requests.put(
    '{{host}}/api/v1/agents/{{id}}/queues',
    json=payload,
    headers=headers, params=params
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Agent queues 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 `agent`	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

PUT `/v1/agents/{id}/recording`

Bật hoặc tắt tính năng ghi âm cho agent. Yêu cầu DBA đã chạy migration_add_is_record.sql trước.

Authentication: Header X-Api-Key (scope: agent). 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`	agentId = extension number	082018

Request Body

{
  "enabled": true
}

Field	Bắt buộc	Mô tả
`enabled`	Có	true = bật ghi âm, false = tắt ghi âm

Code mẫu

curl -X PUT "https://xapi.alohub.vn/v1/agents/082018/recording" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

# Tắt ghi âm
curl -X PUT "https://xapi.alohub.vn/v1/agents/082018/recording" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

const axios = require('axios');
const response = await axios.put(
  '{{host}}/api/v1/agents/{{id}}/recording',
  {
  "enabled": true
},
  { 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 = {
    "enabled": true
}
response = requests.put(
    '{{host}}/api/v1/agents/{{id}}/recording',
    json=payload,
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Recording enabled for agent 082018"
}

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`	"Recording enabled/disabled for agent {id}"

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 `agent`	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ý agents

API Quản lý Agent

GET /v1/agents

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

PUT /v1/agents/{id}/queues

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

PUT /v1/agents/{id}/recording

Tham số

Request Body

Code mẫu

Response 200

Response Fields

Error Codes

Rate Limit Headers

GET `/v1/agents`

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

PUT `/v1/agents/{id}/recording`