Đăng ký API
Để thực hiện các request đến hệ thống API, cần có một tài khoản API. Tài khoản API có dạng
Tên | Kiểu dữ liệu | Giải thích |
appId | String | Định danh tài khoản API |
appSecret | String | khóa bí mật của tài khoản API |
Lưu ý: appId và appSecret sử dụng để chứng thực và kiểm tra dữ liệu của tài khoản API và không có thời gian hết hạn. Do đó, cần được bảo mật thận trọng. Các request đến AntBuddy cần được thực hiện server-to-server để bảo mật. |
Danh sách Call center APIs
1. Lấy danh sách cuộc gọi
1.1. Thông tin
Trường thông tin | Nội dung |
URL | /oapi/v1/call/histories |
Method | GET |
Content Type | application/json |
1.2. Tham số
Tham số | Kiểu dữ liệu | Mô tả |
appId | String | Định danh 3rd party |
created_from | String | Ngày bắt đầu |
created_to | String | Ngày kết thúc |
limit | Number | Giới hạn số record trên 1 trang. Mặc định 20 |
page | Number | Trang hiện tại, mặc định 1 |
hash | String | sha256(appId+created_from+created_to+limit+page+appSecret) |
1.3. Kết quả
Thuộc tính | Ví dụ | Mô tả |
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