Danh sách API (API List)

Lấy token chứng thực

Sử dụng cho việc nhận auth_token websocket về các signal của cuộc gọi. Lấy được giá trị auth_token, truyền auth_token để kết nối websocket nhận thông tin cuộc gọi

URL: /oapi/v1/voice/auth_token

METHOD: POST

Content Type: application/json‌

Headers

Header

Kiểu

Mô tả

x-auth-app-id

String

Định danh 3rd party

x-auth-app-hash

String

sha256(appId + appSecret)

Kết quả

Status

Kết quả

200

{ value: <auth_token>, expire: <expire time> }

Đăng ký nhận tín hiệu từ Websocket

Kết nối WebSocket

Khởi tạo kết nối Socket.IO tới server AntBuddy. Gọi io.connect() khi ứng dụng khởi động. Kết nối này được dùng chung cho toàn bộ các bước phía sau.

const socket = io.connect('https://ws.antbuddy.com:5557');

Đăng ký sự kiện

Sau khi kết nối, gọi socket.emit("subscribe", payload) để đăng ký và xác thực với server. Mỗi lần gọi chỉ đăng ký một loại sự kiện

socket.emit("subscribe", {

account_id: "<account_id>",

auth_token: "<auth_token>",

binding: "call.CHANNEL_CREATE.*"

});

socket.emit("subscribe", {

account_id: "<account_id>",

auth_token: "<auth_token>",

binding: "call.CHANNEL_ANSWER.*"

});

socket.emit("subscribe", {

account_id: "<account_id>",

auth_token: "<auth_token>",

binding: "call.CHANNEL_DESTROY.*"

});

Binding

Kích hoạt khi

call.CHANNEL_CREATE.*

Cuộc gọi mới được tạo / đổ vào hàng đợi

call.CHANNEL_ANSWER.*

Cuộc gọi được trả lời / agent nhấc máy

call.CHANNEL_DESTROY.*

Cuộc gọi kết thúc / cúp máy

Nhận và xử lý sự kiện

Khai báo callback để xử lý data khi server push sự kiện về. Mỗi socket.on() tương ứng với một loại sự kiện đã đăng ký ở Bước 2. Object data chứa thông tin chi tiết của cuộc gọi.

socket.on("CHANNEL_CREATE", (data) => {

console.log(data, 'CHANNEL_CREATE');

});

socket.on("CHANNEL_ANSWER", (data) => {

console.log(data, 'CHANNEL_ANSWER');

});

socket.on("CHANNEL_DESTROY", (data) => {

console.log(data, 'CHANNEL_DESTROY');

});

Các thông tin trong bản tin Websocket

Tên tham số

Bắt buộc

call_id

ID duy nhất của cuộc gọi, nhất quán qua cả 3 sự kiện

caller_id_number

Số điện thoại người gọi

destination_number

Số đích (hotline / extension)

direction

"inbound" hoặc "outbound"

duration

Thời lượng cuộc gọi (giây) — có trong CHANNEL_DESTROY

hangup_cause

Lý do kết thúc, vd: "NORMAL_CLEARING"

Timestamp

Thời gian bắt đầu (theo gregorian)

Click to call

URL: /oapi/v1/call/click-to-call/:number

METHOD: POST

Content Type: application/json‌

Headers:

Thuộc tính

Kiểu dữ liệu

Giá trị

x-auth-app-id

String

Định danh 3rd party

x-auth-app-hash

String

sha256(appId + appSecret)

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

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

note

Để nhận được cuộc gọi, device sip cần register lên hệ thống, mã lỗi 400 là do device chưa register đến hệ thống

Lấy danh sách cuộc gọi

URL: https://openapi.antbuddy.com/oapi/v1/call/histories

METHOD: GET‌

Content Type: application/json‌

Tham số:

Thuộc tính

Kiểu dữ liệu

Giá trị

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(created_from+created_to+limit+page+appID+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

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. UNSUCCESS: Các lỗi khác

duration_seconds

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

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.

Giới hạn:‌ Chỉ cho phép lấy lịch sử cuộc gọi tối đa 31 ngày‌

Lấy file ghi âm

URL: https://openapi.antbuddy.com/oapi/v1/call/play_recording

METHOD: GET‌

Content Type: application/json‌

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)

Kết quả:‌

Đường dẫn URL của file media

Thuộc tính

Ví dụ

Mô tả

media

https://abs1.antbuddy.com/nkrecord/call_recording_F5879958-1A1211E8-A55AA457-72574952%40172.16.0.204.mp3?AWSAccessKeyId=E7IPYE4LN28Y4I6T4400&Expires=1519640615&Signature=wXNENYxr0OJR8vA26kvOOwsttzU%3D

Đường dẫn file ghi âm

(

Used for receiving websocket signals for call events.Comment

URL: /oapi/v1/voice/auth_tokenComment
METHOD: POSTComment
Content Type: application/jsonComment

CommentHeaders:Comment

Property

Data Type

Value

x-auth-app-id

String

3rd party identifier

x-auth-app-hash

String

sha256(appId + appSecret)

CommentResponse:Comment

Status

Result

200

{ value: <auth_token>, expire: <expire time> }

Comment

Comment2. Click to CallComment

URL: /oapi/v1/call/click-to-call/:numberComment
METHOD: POSTComment
Content Type: application/jsonComment

CommentHeaders:Comment

Property

Data Type

Value

x-auth-app-id

String

3rd party identifier

x-auth-app-hash

String

sha256(appId + appSecret)

CommentParameters:Comment

Property

Data Type

Value

sipUser

String

Device name for click to call

sipPassword

String

Password

Response:

Status

Result

200

Device online, click to call successful

400

Device offline, click to call failed

Note: To receive the call, the SIP device must be registered on the system. Error 400 occurs when the device is not registered.

3. Get Call History

URL: https://openapi.antbuddy.com/oapi/v1/call/histories
METHOD: GET
Content Type: application/json

Parameters:

Property

Data Type

Value

appId

String

3rd party identifier

created_from

String

Start date

created_to

String

End date

limit

Number

Limit of records per page, default 20

page

Number

Current page, default 1

hash

String

sha256(created_from+created_to+limit+page+appID+appSecret)

Notes:

Maximum time filter is 31 days.
Default limit is 20 records, maximum 100.
Default page is 1.

Response:

Property

Example

Description

caller

{number: "01693608879", type: "realnumber"}

Caller details, with username if type=user

callee

{number: "thutranhtkbee", type: "user", username: "thutran"}

Callee details, with username if type=user

class

trunking

Call type: one_one for internal, trunking for inbound/outbound calls

did_number

02873019555

DID number for the company. Null if internal or outbound

direction

from_ab

from_ab for outbound calls, to_ab for inbound

status_detail

SUCCESS

Call status: IVR (system call not answered), SUCCESS, CANCELLED, BUSY, UNSUCCESS

duration_seconds

Duration of the call in seconds

unix_timestamp

1519639917

Call timestamp in Unix format

billing_seconds

Talk time for the call in seconds

recording

call_recording_dl5m5j5hfh4n8njj1oor.mp3

File path for the recording, empty if no recording

queue_stat

[ { "_id": "65fa9d8c1b2e4a7c9e001234", "call_id": "call_1707286400@pbx.antbuddy", "queue_id": "queue_support_01", "__v": 0, "org": "org_625e200826e8844fa2cd673c", "wait_time": 12, "caller_id_number": "0987654321", "caller_id_name": "0987654321", "status": "processed", "entered_timestamp": 1707286388, "handled_timestamp": 1707286400, "processed_timestamp": 1707286520, "agent_id": "agent_support01", "username": "support01", "talk_time": 95, "hung_up_by": "agent", "end_call_reason": "agent_hungup", "misses": [] } ]

When there is no queue: []

Limit: The call history can only be retrieved for a maximum of 31 days.

4. Get Call Recording

URL: https://openapi.antbuddy.com/oapi/v1/call/play_recording
METHOD: GET
Content Type: application/json

Parameters:

Property

Data Type

Description

appId

String

3rd party identifier

media

String

Recording file name

hash

String

sha256(appId + media + appSecret)

Response:

Property

Example

Description

media

https://abs1.antbuddy.com/nkrecord/call_recording_F5879958-1A1211E8-A55AA457-72574952%40172.16.0.204.mp3?AWSAccessKeyId=E7IPYE4LN28Y4I6T4400&Expires=1519640615&Signature=wXNENYxr0OJR8vA26kvOOwsttzU%3D

URL link to the recording file

5. Get Dashboard

URL: https://openapi.antbuddy.com/oapi/v1/call/dashboard
METHOD: GET
Content Type: application/json

Parameters:

Property

Data Type

Description

appId

String

3rd party identifier

domain

String

Recording file name

String

Email thuộc công ty

hash

String

sha256(appID+domain+email+appSecret)

Response

Property

Example

Description

agent

{ "ready": 2, "logged_out": 1, "wrapup": 0, "logged_in": 3, "connected": 0, "paused": 0, "status_details": [ { "timestamp": 63936806933, "status": "ready", "id": "df67983ccdeee7d834e8f5d345db1f45::63936806933", "agent_id": "df67983ccdeee7d834e8f5d345db1fe5", "start_idle_time": 63936806933, "idle_time": 765140, "waiting_calls": [], "unix_timestamp": 1769587733, "username": "nguyenvana", "name": "Nguyễn Văn A" }, ] }

The number of employees by status and status details; if not in the list, then logged out.

queue

{

"abandoned": 0,

"abandoned_detail": {},

"offered": 12,

"handled": 12,

"avg_waiting": 6,

"max_waiting": 15,

"avg_talking": 180,

"abandoned_calls": 0,

"received": 12,

"status_details": [],

"waiting_call_logs": []

}

Total calls (calls that have been added to the group)

6. Get queue(Group)

URL: https://openapi.antbuddy.com/oapi/v1/queues
METHOD: GET
Content Type: application/json

Parameters

Property

Data Type

Description

appId

String

3rd party identifier

domain

String

Recording file name

String

Email thuộc công ty

hash

String

sha256(appID+domain+email+appSecret)

Response

Property

Example

Description

name

"Staging Queue"

queue name

agents

[ "Eab4ebf976c53d22d393e94f3ed085dc",

"da80ca52e8ab9d6b26b7f2eb960545ae"

]

Agents in the queue

7. Get agents

URL: https://openapi.antbuddy.com/oapi/v1/agents
METHOD: GET
Content Type: application/json

Parameters

Property

Data Type

Description

appId

String

3rd party identifier

domain

String

Recording file name

String

Email thuộc công ty

hash

String

sha256(appID+domain+email+appSecret)

Response

Property

Example

Description

anttel.userId

“eab4ebf976c53d22d393e94f3ed085dc“

Id agent

username

"userstaging2"

user name

name

"User Staging 2"

agent name

ext

[‘8000’, ‘8001’]

Internal number

PreviousSử dụng API (Use API)NextHướng dẫn sử dụng API Agent/Queue Management

Last updated 2 months ago

Lấy token chứng thực

Headers

Kết quả

Đăng ký nhận tín hiệu từ Websocket

Kết nối WebSocket

Đăng ký sự kiện

Nhận và xử lý sự kiện

Các thông tin trong bản tin Websocket

Click to call​

Lấy danh sách cuộc gọi​

Lấy file ghi âm​

Click to call

Lấy danh sách cuộc gọi

Lấy file ghi âm