Cuộc gọi, Tra cứu & Ghi âm

1. Tổng quan

Base URL

{{protocol}}://{{host}}:{{port}}/api

Lưu ý: Các thông số protocol, host, port sẽ do Alohub cung cấp. Liên hệ đăng ký tích hợp.

Xác thực (Authentication)

Mọi request đều yêu cầu header Authorization chứa API Key do Alohub cung cấp (liên hệ nhận key):

Authorization: {{api-key}}

Header	Giá trị	Mô tả
`Authorization`	`{{api-key}}`	API Key do Alohub cung cấp. Liên hệ Alohub để nhận API Key
`Content-Type`	`application/json`	Định dạng body request (áp dụng cho POST)

Bảo mật: Không chia sẻ API Key ra bên ngoài. Không commit API Key vào source code. Luôn lưu trữ trong biến môi trường (environment variable).

2. Thực hiện cuộc gọi

POST `/v1.0/base/makeCall`

Thực hiện cuộc gọi ra (click-to-call). Hệ thống sẽ gọi đến IP Phone của agent trước, sau khi agent nhấc máy sẽ tự động gọi đến số khách hàng.

Tham số	Bắt buộc	Kiểu	Mô tả
`phoneNumber`	Có	string	Số điện thoại khách hàng cần gọi
`ipPhone`	Có	string	Mã IP Phone (extension) của agent thực hiện cuộc gọi
`transactionId`	Không	string	ID giao dịch để tracking — hữu ích khi cần đối soát hoặc tra cứu sau này

Code mẫu

{
  "phoneNumber": "0123456789",
  "ipPhone": "6688",
  "transactionId": "ALOHUB_3432323435545"
}

curl -X POST "{{protocol}}://{{host}}:{{port}}/api/v1.0/base/makeCall" \
  -H "Authorization: {{api-key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "0123456789",
    "ipPhone": "6688",
    "transactionId": "ALOHUB_3432323435545"
  }'

Gợi ý: Nên truyền transactionId duy nhất cho mỗi cuộc gọi để dễ dàng tra cứu và đối soát với hệ thống nội bộ của bạn.

3. Tra cứu cuộc gọi

Tra cứu lịch sử cuộc gọi theo nhiều tiêu chí.

POST `/v1.0/base/searchCallV2`

Tra cứu lịch sử cuộc gọi phiên bản V2. Tra cứu chi tiết cuộc gọi với đầy đủ thông tin.

Khuyến nghị: Sử dụng V2 cho các tích hợp mới để nhận đầy đủ thông tin cuộc gọi.

Response mẫu

{
  "call_id": "20210222084953-NSOJCGOO-49278",
  "source": "ipcc",
  "direction": "OUTBOUND",
  "call_status": "answered",
  "starttime": "2024-01-13 15:00:30",
  "answertime": "2024-01-13 15:00:35",
  "endtime": "2024-01-13 15:05:30",
  "total_duration": "300",
  "holding_duration": "0",
  "hangup_by": "customer",
  "recording_url": "url_file.mp3",
  "caller_number": "0389900xxx",
  "destination_number": "888",
  "transactionId": "TRANSID_1111",
  "agent": "userName66"
}

Trường	Kiểu	Mô tả
`call_id`	string	Mã định danh duy nhất của cuộc gọi
`source`	string	Nguồn cuộc gọi
`direction`	string	Hướng cuộc gọi: `INBOUND` / `OUTBOUND`
`call_status`	string	Trạng thái cuộc gọi (xem bảng mã trạng thái)
`starttime`	string	Thời điểm bắt đầu cuộc gọi
`answertime`	string	Thời điểm cuộc gọi được trả lời
`endtime`	string	Thời điểm kết thúc cuộc gọi
`total_duration`	string	Tổng thời lượng cuộc gọi (giây)
`holding_duration`	string	Thời gian giữ máy (giây)
`hangup_by`	string	Bên ngắt máy: `customer` / `agent` / `system`
`recording_url`	string	URL file ghi âm cuộc gọi
`caller_number`	string	Số điện thoại bên gọi
`destination_number`	string	Số điện thoại bên nhận
`transactionId`	string	ID giao dịch (nếu có truyền khi makeCall)
`agent`	string	Tên user agent xử lý cuộc gọi

4. Ghi âm cuộc gọi

GET `/IPCCMedia/MP3Export.do`

Phát hoặc tải xuống file ghi âm cuộc gọi. URL đầy đủ được trả về trong trường recording_url của response tra cứu cuộc gọi.

Tham số	Bắt buộc	Kiểu	Mô tả
`url`	Có	string	Tên file MP3 (lấy từ `recording_url` trong kết quả tra cứu)
`source`	Có	string	Nguồn dữ liệu, mặc định `ipcc`

Code mẫu

# Phát trực tiếp (stream)
curl "https://{{domain}}:{{port}}/IPCCMedia/MP3Export.do?url=recording_url.mp3&source=ipcc" \
  -H "Authorization: {{api-key}}"

# Tải xuống file
curl -o recording.mp3 \
  "https://{{domain}}:{{port}}/IPCCMedia/MP3Export.do?url=recording_url.mp3&source=ipcc" \
  -H "Authorization: {{api-key}}"

Lưu ý: File ghi âm có thời hạn lưu trữ tùy theo gói dịch vụ. Nếu cần lưu trữ lâu dài, hãy tải file về hệ thống của bạn.

5. Quản lý Queue

POST `/setting/agent/updateQueue`

Cập nhật cấu hình queue gọi vào (CALLIN) và gọi ra (CALLOUT) cho agent. Sử dụng để phân phối cuộc gọi đến đúng nhóm agent.

Query Parameters:

Tham số	Bắt buộc	Mô tả
`userName`	Có	Tên tài khoản agent cần cập nhật queue

Body Parameters:

Tham số	Bắt buộc	Kiểu	Mô tả
`action`	Có	string	Hành động: `EDIT` (cập nhật toàn bộ) hoặc `ADD` (thêm mới)
`callinId`	Có	array	Danh sách Queue ID gọi vào (callin). VD: `[1, 2]`
`calloutId`	Không	number	Queue ID gọi ra (callout)
`lstExtension`	Không	array	Danh sách extension (IP Phone) gắn với agent

Code mẫu

{
  "action": "EDIT",
  "callinId": [1, 2],
  "calloutId": 99999,
  "lstExtension": ["6688"]
}

curl -X POST "{{protocol}}://{{host}}:{{port}}/api/setting/agent/updateQueue?userName=userName66" \
  -H "Authorization: {{api-key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "EDIT",
    "callinId": [1, 2],
    "calloutId": 99999,
    "lstExtension": ["6688"]
  }'

Webhook: Alohub gửi sự kiện cuộc gọi real-time qua webhook. Xem chi tiết payload, mã trạng thái và cách xử lý tại bài Webhook sự kiện cuộc gọi.

Cuộc gọi, Tra cứu & Ghi âm

1. Tổng quan

Base URL

Xác thực (Authentication)

2. Thực hiện cuộc gọi

POST /v1.0/base/makeCall

Code mẫu

3. Tra cứu cuộc gọi

POST /v1.0/base/searchCallV2

Response mẫu

4. Ghi âm cuộc gọi

GET /IPCCMedia/MP3Export.do

Code mẫu

5. Quản lý Queue

POST /setting/agent/updateQueue

Code mẫu

Related Articles

POST `/v1.0/base/makeCall`

POST `/v1.0/base/searchCallV2`

GET `/IPCCMedia/MP3Export.do`

POST `/setting/agent/updateQueue`