API Tổng đài PBX
Tổng quan các API điều khiển cuộc gọi Click-to-Call, quản lý máy nhánh, danh bạ, luật khách quen và tra cứu lịch sử cuộc gọi.
Nhóm API Tổng đài PBX cung cấp các giao diện lập trình trực tiếp vào lõi tổng đài ODS, cho phép hệ thống quản trị của doanh nghiệp (CRM, ERP, HRM, Helpdesk) tự động hóa toàn bộ vòng đời liên lạc: từ cấp phát máy nhánh, kích hoạt cuộc gọi ra, định tuyến cuộc gọi vào thông minh, đến đồng bộ lịch sử và trích xuất file ghi âm.
Thông tin kết nối chuẩn:
- Base URL chính thức:
https://api.ods.vn - Giao thức: HTTP
POSTvới dữ liệu đóng gói dạngapplication/json; charset=utf-8. - Xác thực: Gửi kèm
AuthUser,AuthKeyvàServiceName(hoặcServiceCode) trong phần thân JSON.
1. Phân loại: Thao tác điều khiển vs Tra cứu dữ liệu
Để thiết kế kiến trúc tích hợp tối ưu, lập trình viên cần phân biệt rõ hai nhóm tác vụ chính:
| Đặc tính | Nhóm Thao tác điều khiển (Execution / Control) | Nhóm Tra cứu dữ liệu (Query / Analytics) |
|---|---|---|
| Bản chất | Tác động trực tiếp vào trạng thái viễn thông hoặc thay đổi cấu hình dữ liệu trên tổng đài. | Đọc dữ liệu lịch sử cuộc gọi, file ghi âm và báo cáo tổng hợp từ database tổng đài. |
| Các API tiêu biểu | AutoCall (Click-to-Call V1), AutoCallV2 (Click-to-Call V2), AddExtension, DeleteExtension, AddPhoneBook, CreateAndUpdateFamiliar. | GetCallLogs, GetCallHistory, GetCallHistoryV2. |
| Đặc điểm phản hồi | Thường trả về ngay trạng thái tiếp nhận (result: "success") kèm mã đối chiếu keySearch hoặc ID bản ghi vừa tạo. | Trả về mảng danh sách bản ghi data kèm tổng số lượng total, hỗ trợ phân trang qua PageIndex và PageSize. |
| Lưu ý triển khai | Tuyệt đối không gọi lặp lại (Retry) thiếu kiểm soát khi mạng chập chờn để tránh phát sinh nhiều cuộc gọi ra cùng lúc. | Nên giới hạn khoảng thời gian lọc (DateStart, DateEnd) để tối ưu tốc độ truy vấn và dung lượng băng thông. |
2. Bảng tra cứu API theo nhu cầu nghiệp vụ
| Nhu cầu của doanh nghiệp | API tương ứng | Mã dịch vụ | Endpoint chi tiết |
|---|---|---|---|
| Cấp số nội bộ mới cho nhân viên tư vấn | AddExtension | ServiceCode | Tạo máy nhánh |
| Thu hồi số nội bộ khi nhân sự nghỉ việc | DeleteExtension | ServiceCode | Xóa máy nhánh |
| Bấm gọi từ CRM: Máy nhánh nhân viên nghe chuông trước rồi mới gọi khách | AutoCall (V1) | ServiceName | Click-to-Call V1 |
| Bấm gọi từ web: Gọi khách trước, khách nghe máy mới chuyển vào nhóm trực/IVR | AutoCallV2 (V2) | ServiceName | Click-to-Call V2 |
| Thêm tên khách hàng vào danh bạ để hiển thị tên khi chuông reo | AddPhoneBook | ServiceName | Thêm danh bạ |
| Khách VIP gọi vào tự động chuyển thẳng về nhân viên phụ trách | CreateAndUpdateFamiliar | ServiceName | Cấu hình Luật khách quen |
| Tra cứu nhật ký cuộc gọi đầy đủ nhất (thời lượng, cước phí, ghi âm) — Khuyến nghị | GetCallLogs | ServiceName | Tra cứu nhật ký cuộc gọi |
| Tra cứu lịch sử cuộc gọi V1 (API cũ — cấu trúc tiếng Việt legacy) | GetCallHistory | ServiceName | Lấy lịch sử cuộc gọi V1 |
| Tra cứu lịch sử cuộc gọi V2 (API cũ — chuẩn camelCase) | GetCallHistoryV2 | ServiceName | Lấy lịch sử cuộc gọi V2 |
3. Khám phá các phân hệ chi tiết
Khởi tạo cuộc gọi (Click-to-Call)
So sánh và tích hợp Click-to-Call V1 (gọi nhân viên trước) và Click-to-Call V2 (gọi khách hàng trước).
Quản lý máy nhánh (Extensions)
Tự động tạo mới và thu hồi số nội bộ, đồng bộ tài khoản thoại với hệ thống nhân sự nội bộ.
Nhật ký cuộc gọi & File ghi âm
Truy xuất CDR chi tiết với GetCallLogs, tải file ghi âm cuộc gọi, đối soát cước và mã KeySearch.
Định tuyến & Luật khách quen
Đồng bộ danh bạ khách hàng và thiết lập luật ưu tiên kết nối khách quen về đúng nhân viên phụ trách.