Register API
To make requests to the API system, you need an API account. The API account has the form
Name | Data type | Explanation |
appId | String | API account identification |
appSecret | String | API account secret key |
Note: appId and appSecret use to authenticate and verify API account data and has no expiration time. Therefore, it needs to be secured with caution. Requests to AntBuddy need to be made server-to-server for security. |
Call center APIs list
1. Get the call list
1.1. Information
Information field | Content |
URL | /oapi/v1/call/histories |
Method | GET |
Content Type | application/json |
1.2. Parameter
Parameter | Data type | Description |
appId | String | 3rd party identification |
created_from | String | Start date |
created_to | String | End date |
limit | Number | Limit the number of records on 1 page. Default 20 |
page | Number | Current page, default 1 |
hash | String | sha256(appId+created_from+created_to+limit+page+appSecret) |
1.3. Result
Property | Example | Description |
caller | { number:"01693608879",
type:"realnumber"
} | Mô tả người gọi. Đối với type=user, có thêm trường username để định danh user. |
callee | {
number:"thutranhtkbee",
type:"user",
username:"thutran"
} | Mô tả người nhận. Đối với type=user, có thêm trường username để định danh user. |
class | trunking | one_one: gọi nội bộ. trunking: gọi ra hoặc gọi vào hệ thống |
did_number | 02873019555 | Số DID của công ty.
Null: nếu gọi nội bộ hoặc gọi ra |
direction | from_ab | from_ab: gọi ra. to_ab: gọi vào |
status_detail | SUCCESS | IVR: Cuộc gọi vào / ra đến hệ thống đầu cuối nhưng người nhận chưa bắt máy.
SUCCESS: Cuộc gọi thành công.
CANCELLED: Thực hiện cuộc gọi ra và gác máy trước khi người nhận nhận cuộc gọi.
BUSY: Thực hiện cuộc gọi ra nhưng đầu nhận bận máy.
ERROR: Các lỗi khác |
duration_seconds | 50 | Thời gian cuộc gọi ( tính bằng giây) |
unix_timestamp | 1519639917 | Thời điểm xảy ra cuộc gọi. Tính theo unix timestamp |
billing_seconds | 43 | Thời gian đàm thoại của cuộc gọi ( tính bằng giây) |
recording | call_recording_dl5m5j5hfh4n8njj1oor.mp3 | File ghi âm. Trường hợp không có ghi âm thì trường này rỗng. |
Lưu ý: Giới hạn chỉ cho phép lấy lịch sử cuộc gọi tối đa 31 ngày |
2. Lấy file ghi âm
2.1. Thông tin
Trường thông tin | Nội dung |
URL | /oapi/v1/call/play_recording |
Method | GET |
Content Type | application/json |
2.2. Tham số
Tham số | Kiểu dữ liệu | Mô tả |
appId | String | Định danh 3rd party |
media | String | Tên file recording |
hash | String | sha256(appId +media+ appSecret) |
2.3. Kết quả
Thuộc tính | Ví dụ |
media | https://abs1.antbuddy.com/nkrecord/call_recording_F5879958-1A1211E8-A55AA457-72574952%40172.16.0.204.mp3?AWSAccessKeyId=E7IPYE4LN28Y4I6T4400&Expires=1519640615&Signature=wXNENYxr0OJR8vA26kvOOwsttzU%3D |
3. Click to call
3.1. Thông tin
Trường thông tin | Nội dung |
URL | /oapi/v1/call/click-to-call/:number |
Method | POST |
Content Type | application/json |
3.2. Header
Thuộc tính | Kiểu dữ liệu | Giá trị |
x-auth-app-id | String | Định danh 3rd party |
x-auth-app- | Str | sha256(appId + appSecret) |
3.2. Tham số
Thuộc tính | Kiểu dữ liệu | Giá trị |
sipUser | String | Device name thực hiện việc click to call |
sipPassword | String | Mật khẩu |
3.3. Kết quả
status | Kết quả |
200 | Device online, click to call thành công |
400 | Device offline, click to call thất bại |
4. Get auth token
4.1. Thông tin
Trường thông tin | Nội dung |
URL | /oapi/v1/voice/auth_token |
Method | POST |
Content Type | application/json |
4.2. Header
Thuộc tính | Kiểu dữ liệu | Giá trị |
x-auth-app-id | String | Định danh 3rd party |
x-auth-app- | Str | sha256(appId + appSecret) |
4.2. Tham số
Thuộc tính | Kiểu dữ liệu | Giá trị |
sipUser | String | Device name thực hiện việc click to call |
sipPassword | String | Mật khẩu |
4.3. Kết quả
status | Kết quả |
200 | {
value: <auth_token>,
expire: <expire time>
} |
Sử dụng Call center APIs
1. Giới thiệu
Sau khi đăng ký và được cấp tài khoản API, khách hàng sẽ được cấp một appId và appSecret. Khi gọi API, phải sử dụng appSecret này để tạo một tham số hash. Chi tiết các tạo tham số hash trong mục Tạo Hash và có chi tiết trong từng API.
Các request đến API thực hiện đến tên miền
https://openapi.antbuddy.com |
Tùy vào từng API mà phương thức và đường dẫn sẽ khác nhau.
2. Tạo Hash
Tất cả request đến AntBuddy ngoài dữ liệu, phải kèm theo một giá trị hash. Hash được tính là sha256 của tất cả các tham số (ngoài trừ hash)
Ví dụ:
Thuộc tính | Giá trị |
appId | 65446465436742018 |
appSecret | 123456 |
API lấy lịch sử cuộc gọi
Method | URL |
GET | /oapi/v1/call/histories?appId=6544646543674&created_from=2018-02-07T02:19:33.000Z&created_to=2018-02-07T07:04:22.000Z |
Thì hash được tính như sau:
hash = sha256(“65446465436742018-02-07T02:19:33.000Z2018-02-07T07:04:22.000Z123456”) |
= 9b11b9ff77dbba70fe059acf84c02cfe6af90de9122e4d3bd6ec69c9d637f9ed |
Lưu ý thứ tự của các tham số của từng API
var crypto = require('crypto');
function checksum (str) {
return crypto
.createHash('sha256')
.update(str, 'utf8')
.digest('hex')
}
var text = '65446465436742018-02-07T02:19:33.000Z2018-02-07T07:04:22.000Z123456';
var hash = checksum(text);
//9b11b9ff77dbba70fe059acf84c02cfe6af90de9122e4d3bd6ec69c9d637f9ed |
3. Định dạng dữ liệu
Dữ liệu được gửi lên và trả về đều ở định dạng JSON
"Content-Type": "application/json" |
4. HTTP Response
HTTP Code | Chú thích |
200 | Thành công |
400 | Lỗi do dữ liệu đầu vào không đúng hoặc không hợp lệ |
500 | Lỗi do máy chủ API |
503 | Lỗi do vượt quá giới hạn số request |
Mã Lỗi Call center APIs
Khi có lỗi API trả về có dạng:
{
success: false,
message: <MESSAGE>
} |
Trong đó MESSAGE được mô tả trong bảng dưới:
MESSAGE | Chú thích |
APPID_NOT_FOUND | appId không tìm thấy |
APPID_MISSING | Thiếu tham số appId |
HASH_NOT_MATCH | Giá trị tham số hash không đúng |
METHOD_NOT_SUPPORT | Phương thức không hỗ trợ |
Liên hệ 1900 63 64 12 hoặc openapi@antbuddy.com để đăng ký tài khoản API