AntRing - AntRing APIs

Đă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)



Trong đó:‌

  • Thời gian filter tối đa là 31 ngày

  • Limit mặc định là 20 record, tối đa 100

  • Page mặc định là 1

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


Bài viết này có hữu ích không? Đánh giá: 0
Chi tiết bài viết:
Ngày đăng: 23/11/2020 4:51PM
Lần cập nhật gần đây: 04/01/2021 3:26PM (manle - man.le@antbuddy.com)
Chia sẻ bài viết:   
Tác giả:manle (man.le@antbuddy.com)