TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL - FTI · 2020. 12. 1. · FPT TELECOM INTERNATIONAL HOTLINE: 1900 6973 3 TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL - Output: Trường

TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL

FPT TELECOM INTERNATIONAL HOTLINE: 1900 6973

1 TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL

I. API

1. API LẤY ACCESS TOKEN

1.1 SỬ DỤNG USER/PASSWORD CỦA TENANT

- Phạm vi áp dụng của access token: cho phép truy cập và lấy thông tin của Tenant.

- URL: http://118.68.169.39:8899/api/account/credentials/verify

- Content-Type: application/json

- Method: POST

- Input:

Tên tham số Kiểu dữ liệu Bắt buộc Mô tả

name String Có User của Tenant

password String Có Password của Tenant

- Ví dụ:

- Output: Trường hợp thành công (Status: 200 OK)

Tên tham số Kiểu dữ liệu Mô tả

access_token String Access token dùng cho tenant

expires Integer Thời gian hết hạn

api_version String Phiên bản sử dụng

role String Loại user

name String Tên user

id Integer ID của tenant

- Ví dụ:

- Output: Trường hợp lỗi (Status: 400 Bad Request)


err_code String Mã lỗi

msg String Nguyên nhân lỗi

http://118.68.169.39:8899/api/account/credentials/verify



- Ví dụ:

1.2 SỬ DỤNG EXTENSION NUMBER / PASSWORD CỦA EXTENSION

- Phạm vi áp dụng của access token: cho phép truy cập và lấy thông tin của Extension.

- URL: http://118.68.169.39:8899/api/account/extension/sip/verify


- Method: POST

- Input:


extension_number String Có Số extension

sip_password String Có Password của Extension

domain String Có Domain Tenant của Extension

- Ví dụ:



access_token String Access token dùng cho Extension

extension_number String Số Extension

extension_password String Password của Extension

indept_password String Password truy cập web của Extension

domain String Domain Tenant của Extension




name String Tên của Extension


transports Array Giao thức / Port của Extension

- Ví dụ:

http://118.68.169.39:8899/api/account/extension/sip/verify







- Ví dụ:

1.3 SỬ DỤNG EXTENSION NUMBER / WEB PASSWORD CỦA EXTENSION

- Phạm vi áp dụng của access token: cho phép truy cập và lấy thông tin của Extension.

- URL: http://118.68.169.39:8899/api/account/extension/web/verify


- Method: POST

- Input:


extension_number String Có Số extension

web_password String Có Password truy cập web của

Extension

domain String Có Domain Tenant của Extension

- Ví dụ:

http://118.68.169.39:8899/api/account/extension/web/verify





access_token String Access token dùng cho Extension


extension_password String Password của Extension

indept_password String Password truy cập web của Extension

domain String Domain Tenant của Extension




name String Tên của Extension


transports Array Giao thức / Port của Extension

- Ví dụ:





- Ví dụ:



2. API LẤY THÔNG TIN LIÊN QUAN ĐẾN EXTENSION:

2.1 HIÊN THI DANH SACH GROUP EXTENSION

- Sử dụng access token ở mục 1.1 để gọi API.

- URL: http://118.68.169.39:8899/api/extensions/group/list


- Method: GET

- Input:


access_token String Có Access token của Tenant (sử

dụng tại header)

pagination Integer Có Số trang chứa thông tin

pagesize Integer Không Số dòng của 1 trang

- Ví dụ:



pagination Integer Số trang chứa thông tin

pagesize Integer Số dòng của 1 trang

sort_by String Phương thức sắp xếp kết quả

count Integer Đếm kết quả trả về

groups Array Thông tin các group Extension:

-id: id của group

-group_name: tên group

-members_count: số extension của

group

- Ví dụ:

http://118.68.169.39:8899/api/extensions/group/list







- Ví dụ:

2.2 HIÊN THI CHI TIẾT CAC EXTENSION TRONG GROUP EXTENSION


- URL: http://118.68.169.39:8899/api/extensions/group/show


- Method: GET

- Input:




id Integer Có ID của group

- Ví dụ:


Tên tham số Kiểu dữ

liệu

Mô tả

id Integer ID của group

group_name String Tên group

group_description String Mô tả group

enable_management_console_access Boolean Cho phép thành viên trong group

được truy cập web

enable_call_cross_group Boolean Cho phép gọi nội bộ giữa thành

viên trong group

enable_intercom Boolean Cho phép tính năng gọi intercom

enable_external_call Boolean Cho phép thành viên trong group

gọi ra PSTN

http://118.68.169.39:8899/api/extensions/group/show



members Array Thông tin thành viên trong group:

-id: ID của Extension

-extension_number: số

Extension

-first_name: tên của Extension

-last_name: họ của Extension

- Ví dụ:





- Ví dụ:

2.3 HIÊN THI THÔNG TIN TẤT CẢ EXTENSION


- URL: http://118.68.169.39:8899/api/extensions/list


http://118.68.169.39:8899/api/extensions/list



- Method: GET

- Input:






- Ví dụ:







extensions Array Thông tin các Extension:

-id: id của Extension

-extension_number: số Extension

-first_name: tên của Extension

-last_name: họ của Extension

-email: địa chỉ mail của Extension

-status: trạng thái của Extension

-user_agent: user agent của

Extension

- Ví dụ:







- Ví dụ:

2.4 HIÊN THI THÔNG TIN CỦA 01 EXTENSION CỤ THÊ

- Sử dụng access token ở mục 1.2 hoặc 1.3 để lấy thông tin ID của Extension và gọi API.

- URL: http://118.68.169.39:8899/api/extensions/show


- Method: GET

- Input:

http://118.68.169.39:8899/api/extensions/show




access_token String Có Access token của Extension (sử


id Integer Có ID của Extension

- Ví dụ:


Tên tham số Kiểu dữ

liệu

Mô tả

id Integer ID của Extension


password String Password của Extension

web_access_password String Password truy cập web của

Extension

profile Array Thông tin profile của Extension

belong_groups Array Thông tin group của Extension

options Array Thông tin liên quan đến cấu hình

của Extension

forward_rules Array Thông tin liên quan đến cấu hình

forward của Extension

voice_mail Array Thông tin liên quan đến cấu hình

Voice Mail của Extension

office_hours Array Thông tin liên quan đến cấu hình

thời gian làm việc của Extension

blfs Array Thông tin liên quan đến cấu hình

BLF của Extension

- Ví dụ:







- Ví dụ:

2.5 HIÊN THI THÔNG TIN QUOTA HIỆN TẠI CỦA 01 EXTENSION CỤ THÊ

- Sử dụng access token ở mục 1.2 hoặc 1.3 để lấy thông tin ID của Extension và gọi API.

- URL: http://118.68.169.39:8899/api/billing/show


- Method: GET

- Input:


access_token String Có Access token của Extension (sử


id Integer Có ID của Extension

http://118.68.169.39:8899/api/billing/show



- Ví dụ:



id Integer Id của Extension

billing String Số tiền còn tại của Extension

currency String Mênh giá tiền

- Ví dụ:





- Ví dụ:

3. API THỰC HIỆN CUỘC GỌI RA TỪ MỘT EXTENSION

3.1 THỰC HIỆN CUỘC GỌI RA TỪ MỘT EXTENSION

- URL: http://118.68.169.39:8899/api/extensions/call


- Method: POST

- Input:


src String Có Số extension dùng để gọi ra

to String Có Số bị gọi

domain String Có Domain tenant của extension

extension String Có

Số extension dùng để chứng thực

cuộc gọi (có thể trùng với tham số

src hoặc không, nhưng phải cùng

tenant)

auth String Có Web Access Password của tham

số extension

http://118.68.169.39:8899/api/extensions/call



- Ví dụ:


4. API LẤY THÔNG TIN FILE GHI ÂM CỦA CUỘC GỌI

4.1 HIÊN THI THÔNG TIN FILE GHI ÂM CỦA CAC CUỘC GỌI


- URL: http://118.68.169.39:8899/api/recordfiles/extension/list


- Method: GET

- Input:






start_time String Không Thời gian bắt đầu cuộc gọi

end_time String Không

Thời gian kết thúc cuộc gọi (nên

đi cùng start_time để trả về thông

tin đúng)

extension String Không Số extension

- Ví dụ:







records Array Thông tin các file ghi âm:

-id: id của cuộc gọi

-filename: tên file

-filepath: thư mục file trên server. Để

tải file ghi âm về thì sử dụng đường

dẫn http://file.oncall.vn/<giá trị

filepath>

-caller: số chủ gọi

http://118.68.169.39:8899/api/recordfiles/extension/list



-callee: số bị gọi

-start_time: thời gian bắt đầu cuộc

gọi

-end_time: thời gian kết thúc cuộc

gọi

-duration: tổng thời gian cuộc gọi

-status: trạng thái đọc file

- Ví dụ:





- Ví dụ:

5. API LẤY THÔNG TIN LICH SỬ CUỘC GỌI

5.1 HIÊN THI LICH SỬ CAC CUỘC GỌI




- URL: http://118.68.169.39:8899/api/call_logs/list


- Method: GET

- Input:






start_time String Không Thời gian bắt đầu cuộc gọi

end_time String Không

Thời gian kết thúc cuộc gọi (nên

đi cùng start_time để trả về thông

tin đúng)

extension String Không Số extension

- Ví dụ:






details Array Thông tin lịch sử các cuộc gọi:

-id: id của cuộc gọi

-caller: số chủ gọi

-callee: số bị gọi

-start_time: thời gian bắt đầu cuộc

gọi

-answer_time: thời gian trả lời cuộc

gọi

-ringing_time: thời gian đổ chuông

-duration: tổng thời gian cuộc đàm

thoại

-ring_duration: tổng thời gian đổ

chuông

-talk_duration: tồng thời gian đàm

thoại

http://118.68.169.39:8899/api/call_logs/list



-direction: phân loại cuộc gọi vào/ra

-end_reason: nguyên nhân kết thúc

cuộc gọi

-status: tình trạng cuộc gọi

-outcid: số đại diện gọi ra

-didcid: số đại diện gọi vào

-call_cost: cước cuộc gọi

- Ví dụ:





- Ví dụ:

5.2 HIÊN THI LICH SỬ CHI TIẾT 01 CUỘC GỌI CỤ THÊ




- URL: http://118.68.169.39:8899/api/call_logs/show


- Method: GET

- Input:




id Integer Có Id của cuộc gọi, được lấy từ mục

4.1

- Ví dụ:




id Integer Id của cuộc gọi

targets Array Thông tin lịch sử cuộc gọi:

-destination: trường số bị gọi

-add_time: thời gian bắt đầu cuộc

gọi

-answer_time: thời gian trả lời cuộc

gọi

-end_time: thời gian kết thúc cuộc

gọi

-ringing_time: thời gian đổ chuông

-fail_code: mã lỗi

-related_callid: thông tin cuộc gọi có

liên quan với cuộc gọi này


chuông

-talk_duration: tổng thời gian đàm

thoại

-direction: phân loại cuộc gọi vào/ra


cuộc gọi

-status: tình trạng cuộc gọi

-target_cost: cước cuộc gọi

http://118.68.169.39:8899/api/call_logs/show



-rating: bảng giá cước cuộc gọi

- Ví dụ:





- Ví dụ:

6. API LẤY THÔNG TIN LIÊN QUAN ĐẾN CALL QUEUE

6.1 HIÊN THI THÔNG TIN CAC CALL QUEUE


- URL: http://118.68.169.39:8899/api/call_queues/list


- Method: GET

- Input:

http://118.68.169.39:8899/api/call_queues/list








- Ví dụ:







queues Array Thông tin các Call Queue:

-id: Id của Call Queue


của Call Queue

-name: tên của Call Queue

-polling_strategy: phương thức đổ

chuông cái máy thành viên của Call

Queue

- Ví dụ:







- Ví dụ:

6.2 HIÊN THI THÔNG TIN CỦA 1 QUEUE CỤ THÊ


- URL: http://118.68.169.39:8899/api/call_queues/show


- Method: GET

- Input:




id Integer Có Id của Call Queue, lấy từ mục 5.1

http://118.68.169.39:8899/api/call_queues/show



- Ví dụ:



id Integer Id của Call Queue

name String Tên của Call Queue

outbound_caller_id String Số đại diện dùng để gọi ra PSTN

extension_number String Số Extension của Call Queue

ring_time Integer Thời gian đổ chuông của Call Queue

polling_strategy String Phương thức đổ chuông cái máy

thành viên của Call Queue

max_callers Integer Số người gọi tối đa vào 01 Call

Queue

moh_fileid String Thông tin file ghi âm nhạc chờ cho

Call Queue

members Array Thông tin các thành viên trong Call

Queue

- Ví dụ:







- Ví dụ:

6.3 HIÊN THI THÔNG TIN CUỘC GỌI ĐANG TRONG HÀNG ĐỢI CỦA 1 QUEUE CỤ

THÊ


- URL: http://118.68.169.39:8899/api/call_queues/wait/list


- Method: GET

-

- Input:

http://118.68.169.39:8899/api/call_queues/wait/list







- Ví dụ:




wait_members Array Thông tin các cuộc gọi đang trong

hang đợi của Call Queue:

-display_name: số chủ gọi

-extension_number: trường số chủ

gọi

-waittime: thời gian đang chờ cuộc

gọi được tiếp nhận

- Ví dụ:





- Ví dụ:

7. API LẤY THÔNG TIN LIÊN QUAN ĐẾN CONFERENCE

7.1 HIÊN THI THÔNG TIN CAC CONFERENCE ROOM




- URL: http://118.68.169.39:8899/api/conference_room/list


- Method: GET

- Input:






- Ví dụ:







rooms Array Thông tin các Conference Room:

-id: Id của Conference Room


của Conference Room

-room_pin: mã Pin của Room

-admin_pin: mã Pin của Admin

Room

-mode: loại Conference Room

-subject: tên của Conference Room

-maximum_participants: số thành

viên tối đa được phép tham gia vào

Room

- Ví dụ:

http://118.68.169.39:8899/api/conference_room/list







- Ví dụ:

7.2 HIÊN THI THÔNG TIN CỦA 01 CONFERENCE ROOM CỤ THÊ


- URL: http://118.68.169.39:8899/api/conference_room/show


- Method: GET

- Input:





http://118.68.169.39:8899/api/conference_room/show



- Ví dụ:



id Integer Id của Conference Room

room_pin String Mã Pin của Room

outbound_caller_id String Số đại diện dùng để gọi ra PSTN

extension_number String Số Extension của Conference Room

subject Integer Tên của Conference Room

admin_pin String Mã Pin của Admin Room

mode String Loại Conference Room

max_participants Integer Số thành viên tối đa được phép tham

gia vào Room

- Ví dụ:





- Ví dụ:



7.3 HIÊN THI THÔNG TIN THÀNH VIÊN ĐANG THAM GIA TRONG 1 ROOM CỤ

THÊ


- URL: http://118.68.169.39:8899/api/conference_room/participants/list


- Method: GET

- Input:




id Integer Có Id của Room, lấy từ mục 6.1

- Ví dụ:




participants Array Thông tin các cuộc gọi đang trong

Room:

-participant: số chủ gọi

-muted: thông tin tính năng “Mute”

- Ví dụ:





- Ví dụ:

http://118.68.169.39:8899/api/conference_room/participants/list



8. API LẤY THÔNG TIN LIÊN QUAN ĐẾN CONTACT

8.1 HIÊN THI THÔNG TIN CAC CONTACT GROUP


- URL: http://118.68.169.39:8899/api/contacts/group/list


- Method: GET

- Input:






- Ví dụ:







contactGroups Array Thông tin các Contact Group:

-id: Id của Contact Group

-count: số contact trong group

-name: tên Contact Group

-description: mô tả Contact Group

- Ví dụ:

http://118.68.169.39:8899/api/contacts/group/list







- Ví dụ:

8.2 HIÊN THI THÔNG TIN CAC CONTACT TRONG 1 GROUP CỤ THÊ


- URL: http://118.68.169.39:8899/api/contacts/list


- Method: GET

- Input:






contact_grpid Integer Có Id của Contact Group, lấy từ mục

7.1

- Ví dụ:


http://118.68.169.39:8899/api/contacts/list








contacts Array Thông tin các Contact trong Group:

-id: Id của Contact

-first_name: tên

-last_name: họ

-company: công ty

-mobile_phone: số điện thoại di

động

-mobile_phone2: số điện thoại di

động 2

-home_phone: số điện thoại cố định

-home_phone2: số điện thoại cố định

2

-email: địa chỉ email

- Ví dụ:







- Ví dụ:

8.3 HIÊN THI THÔNG TIN CỦA 01 CONTACT CỤ THÊ TRONG 1 GROUP CỤ THÊ


- URL: http://118.68.169.39:8899/api/contacts/show


- Method: GET

- Input:




id Integer Có Id của Contact, lấy từ mục 7.2

- Ví dụ:



id Integer Id của Contact

first_name String Tên

last_name String Họ

company String Công ty

mobile_phone String Số điện thoại di động

mobile_phone2 String Số điện thoại di động 2

home_phone String Số điện thoại cố định

home_phone2 String Số điện thoại cố định 2

email String Địa chỉ email

- Ví dụ:

http://118.68.169.39:8899/api/contacts/show







- Ví dụ:

II. EVENT URL - Mục đích: gửi các thông tin liên quan đến chi tiết cuộc gọi và các sự kiện liên quan đến Extension đến

client thông qua Webhook, cụ thể như sau:

Đăng ký Extension

Cuộc gọi đi từ 01 Extension.

Cuộc gọi đến 01 Extension.

- Hướng dẫn cấu hình: tại trang quản trị của Tenant, chọn Profile > Event URL



Tại mục CDR events, cấu hình các thông tin như sau:

o Authentication method: chọn phương pháp chứng thực tương ứng phía client để cho phép

gửi bản tin. Nếu không yêu cầu chứng thực thì chọn “None”

o Username: username dùng để chứng thực.

o Password: password dùng để chứng thực.

o CDR URL: URL của client dùng để nhận các bản tin. Ví dụ: http://

www.clientserver.com/notification.php

o Enable: nhấn chọn để cho phép gửi CDR events đến client.

Tại mục Extension event, cấu hình các thông tin sau:

o Authentication method: chọn phương pháp chứng thực tương ứng phía client để cho phép

gửi bản tin. Nếu không yêu cầu chứng thực thì chọn “None”

o Username: username dùng để chứng thực.

o Password: password dùng để chứng thực.

o Event URL: URL của client dùng để nhận các bản tin. Ví dụ: http://

www.clientserver.com/notification.php

o Enable: nhấn chọn để cho phép gửi Extension event đến client.

- Output của CDR events

Param name Data type Description

answered_time String Thời gian trả lời cuộc gọi (định dạng

UNIX)

http://www.clientserver.com/notification.php

http://www.clientserver.com/notification.php



call_id String Id cuộc gọi

call_status String Trạng thái cuộc gọi

callee String Số bị goi

callee_domain String Domain của số bị gọi

caller String Số chủ gọi

caller_display_name String Tên/Số chủ gọi được hiển thị

caller_domain String Domain của số chủ gọi

did_cid String DID hoặc CID

direction String Phân loại cuộc gọi vào/ra

ended_reason String Nguyên nhân kết thúc cuộc gọi

ended_time String Thời gian kết thúc cuộc gọi (định

dạng UNIX)

fail_code String Mã code lỗi khi cuộc gọi kết thúc

final_dest String Số bị gọi cuối cùng

outbound_caller_id String Số đại diện dùng khi gọi ra

related_callid1 String Id cuộc gọi liên quan 1

related_callid2 String Id cuộc gọi liên quan 2

ring_duration String Tổng thời gian đổ chuông

ring_time String Thời gian đổ chuông (định dạng

UNIX)

start_time String Thời gian bắt đầu cuộc gọi (định

dạng UNIX)

talk_duration String Tổng thời gian đàm thoại

tenant_id String Id của tenant

tenant_name String Tên tenant

call_targets Array Chi tiết cuộc gọi con:

-add_time: thời gian bắt đầu cuộc gọi

(định dạng UNIX)

-answered_time: thời gian trả lời

cuộc gọi (định dạng UNIX)


cuộc gọi

-ended_time: thời gian kết thúc cuộc

gọi (định dạng UNIX)

-fail_code: mã code lỗi khi cuộc gọi

kết thúc

-related_callid: id cuộc gọi liên quan




chuông

-ring_time: thời gian đổ chuông (định

dạng UNIX)

-status: trạng thái cuộc gọi

-talk_duration: tổng thời gian đàm

thoại

-target_number: số bị gọi

-trunk_name: trunk cuộc gọi

- Ví dụ của CDR events



- Output của Extension event


call_id String Id của cuộc gọi

callee String Trường số bị goi

caller String Trường số chủ gọi

event_type String Trạng thái cuộc gọi

tenant_id String Id của tenant

time String Thời gian (định dạng UNIX)



- Ví dụ của Extension event

Documents

TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL - FTI · 2020. 12. 1. · FPT TELECOM INTERNATIONAL HOTLINE: 1900 6973 3 TÀI LIỆU MÔ TẢ API VÀ EVENT URL ONCALL - Output: Trường