v2 Integration

OmiCall Web SDK : là công cụ bao gồm thư viện và tài liệu mà OmiCall cung cấp cho đối tác, để đối tác xây dựng tính năng call ngay chính trên ứng dụng web của mình.

Latest version : 2.1.12
Release date : 08/11/2024
Changelog : https://api.omicall.com/sdk/web-sdk-changelog

Hướng dẫn cài đặt

Nhúng Web SDK vào HTML của website cần tích hợp

<body>

    <!-- other html -->
    
    <script omi-sdk type="text/javascript" src="https://cdn.omicrm.com/sdk/2.0.0/sdk.min.js"></script>
    
    <script>
        document.addEventListener('DOMContentLoaded', () => {
            // Ví dụ về một số config có thể dùng khi init SDK
            let config = {
                theme: 'default',
                callbacks: {
                    register: (data) => {
                        // Sự kiện xảy ra khi trạng thái kết nối tổng đài thay đổi
                        console.log('register:', data);
                    },
                    connecting: (data) => {
                        // Sự kiện xảy ra khi bắt đầu thực hiện cuộc gọi ra
                        console.log('connecting:', data);
                    },
                    invite: (data) => {
                         // Sự kiện xảy ra khi có cuộc gọi tới
                         console.log('invite:', data);
                    },
                    inviteRejected: (data) => {
                         // Sự kiện xảy ra khi có cuộc gọi tới, nhưng bị tự động từ chối
                         // trong khi đang diễn ra một cuộc gọi khác
                         console.log('inviteRejected:', data);
                    },
                    ringing: (data) => {
                        // Sự kiện xảy ra khi cuộc gọi ra bắt đầu đổ chuông
                        console.log('ringing:', data);
                    },
                    accepted: (data) => {
                         // Sự kiện xảy ra khi cuộc gọi vừa được chấp nhận
                         console.log('accepted:', data);
                    },
                    incall: (data) => {
                         // Sự kiện xảy ra mỗi 1 giây sau khi cuộc gọi đã được chấp nhận
                         console.log('incall:', data);
                    },
                    acceptedByOther: (data) => {
                         // Sự kiện dùng để kiểm tra xem cuộc gọi bị kết thúc
                         // đã được chấp nhận ở thiết bị khác hay không
                         console.log('acceptedByOther:', data);
                    },
                    ended: (data) => {
                         // Sự kiện xảy ra khi cuộc gọi kết thúc
                         console.log('ended:', data);
                    },
                    holdChanged: (status) => {
                         // Sự kiện xảy ra khi trạng thái giữ cuộc gọi thay đổi
                         console.log('on hold:', status);
                    },
                    saveCallInfo: (data) => {
                        // let { callId, note, ...formData } = data;
                        // Sự kiện xảy ra khi cuộc gọi đã có đổ chuông hoặc cuộc gọi tới, khi user có nhập note input mặc định hoặc form input custom
                        console.log('on save call info:', data);
		    },
                    infoLastCall: (data) => {
                        // Sự kiện xảy ra khi có bật options.showInfoLastCall và SDK có get được data cho số điện thoại đang gọi
                        console.log('on found info last call:', data);
		    },
                }
            };
            omiSDK.init(config, () => {
                // Truy cập OMICall
                // Vào menu : Cấu hình >> Tổng đài >> Số nội bộ
                // Mở chi tiết 1 số nội bộ để lấy thông tin 
                // omiSDK.register({
                //    domain: 'abc',
                //    username: '100', 
                //    password: '123456'
                // });
                omiSDK.register({
                    domain: '',
                    username: '', // tương đương trường "sip_user" trong thông tin số nội bộ
                    password: ''
                });
            });
            // Cách khác để khai báo các SDK events:
            // omiSDK.on('register', (data) => {
            //     // Sự kiện xảy ra khi trạng thái kết nối tổng đài thay đổi
            //     console.log('register:', data);
            // });
            // Cách khác để huỷ khai báo các SDK events:
            // omiSDK.off('register');
        });
    </script>

</body>

Phương thức

Mô tả

omiSDK.init(config, callback)

Khởi tạo các cấu hình cần thiết cho SDK và load UI nếu có truyền theme

omiSDK.register(params)

Gọi tới khi sau khi function SDK init callback.
Phương thức ghi danh tổng đài: Object

{ domain : "abc" // domain tổng dài

username: "100", // Số nội bộ

password: "***" // Mật khẩu số nội bộ

}

*Lưu ý: Có thể lấy các thông tin ghi danh tổng đài ở cấu hình số nội bộ hoặc thông qua API của OMICall

omiSDK.unregister()

Ngưng kết nối với tổng đài

omiSDK.reregister(params)

Ngưng kết nối với tổng đài và tạo một phiên kết nối mới với params trước đó hoặc từ params mới truyền

omiSDK.makeCall(phone)

- phone:

Số điện thoại khách hàng
Số nội bộ của nhân viên
Số nội bộ của nhóm
Số nội bộ của nhóm bên ngoài

omiSDK.makeCall(phone, hotline) or omiSDK.makeCall(phone, options)

- phone:

Số điện thoại khách hàng
Số nội bộ của nhân viên
Số nội bộ của nhóm
Số nội bộ của nhóm bên ngoài

- hotline (String): đầu số tổng đài dùng để gọi ra (*Lưu ý: phải là đầu số cho phép gọi ra và tài khoản nhân viên thực hiện cuộc gọi được quyền sử dụng đầu số này) - options (Object): { sipNumber: String,

sneakyType: String, datas: { 'User-Data': String } } + sipNumber: như param hotline cũ + sneakyType: loại cuộc gọi giám giát số nội bộ khác, gồm: > monitoring: Giám sát > whisper: Thì thầm > colloquy: Đàm thoại 3 bên + datas: dữ liệu truyền lên tổng đài để lưu thêm dữ liệu tuỳ chỉnh vào lịch sử cuộc gọi, max length của string data là 256

omiSDK.stopCall()

Từ chối cuộc gọi/ Kết thúc cuộc gọi

omiSDK.acceptCall()

Chấp nhận cuộc gọi

omiSDK.transferCall(extension)

Chuyển tiếp cuộc gọi.

extension : Là số máy lẻ nhân viên cần chuyển tới

omiSDK.sendDTMF(tone)

Gửi tín hiệu tương tác bấm phím

tone: các số từ 0-9 hoặc *#

omiSDK.toggleMute(status)

Bật tắt âm thanh từ micro của bạn

status:

true: tắt âm thanh
false: bật âm thanh

omiSDK.toggleHold(status)

Thay đổi trạng thái giữ cuộc gọi

status:

true: giữ cuộc gọi
false: bỏ giữ cuộc gọi

omiSDK.getStatus()

Lấy trạng thái kết nối hiện tại của SDK với tổng đài:

registering: đang kết nối
registered: đã kết nối
unregistered: chưa kết nối

omiSDK.toggleDialog()

Chủ động ẩn hiện dialog cuộc gọi của SDK nếu có sử dụng theme

omiSDK.isCalling()

Trả về giá trị true/false

omiSDK.updateContactInfo(Object)

Cập nhật Tên và Avatar của khách hàng trên cửa số cuộc gọi

omiSDK.updateContactInfo({

name : "Nguyễn Thanh Sang",

avatar : "https://...."

});

*Giá trị avatar sẽ được truyền vào thuộc tính src của thẻ img: có thẻ là http link hoặc base64,...

omiSDK.getAccessToken()

Trả về accessToken của phiên kết nối tổng đài hiện tại, có thể dùng để gọi các API public của OMI

omiSDKTheme.setFormData(Object)

Set value cho các text input với id tương ứng khi truyền mảng "forms" trong cấu hình

omiSDK.setBusy(status)

status (String | Boolean): inbound | outbound | local | all

Cập nhật trạng thái BUSY của SDK, được lưu trong localStorage để đồng bộ giứa các tab của trình duyệt

omiSDK.isBusy(direction)

direction (String): nhận các giá trị của param status khi dùng omiSDK.setBusy(status) (Nếu không truyền, giá trị mặc định là inbound). Trả về trạng thái BUSY hiện tại của SDK theo hướng cuộc gọi.

Dữ liệu callback từ sự kiện

Tham số

Loại

Mô tả

direction

String

Hướng của cuộc gọi: outbound, inbound

directionTxt

String

Tên hướng của cuộc gọi

status

String

Trạng thái hiện tại của cuộc gọi: connecting, ringing, connected, ended, hold

statusTxt

String

Tên trạng thái hiện tại của cuộc gọi

remoteNumber hoặc phone

String

với direction outbound: số được gọi ra
với direction inbound: số đang gọi tới

sipDomain

String

Domain tổng đài của phiên kết nối hiện tại

sipUser

String

Số nội bộ của phiên kết nối hiện tại

sipNumber

String

Số tổng đài đang dùng để thực hiện cuộc gọi ra hay nhận cuộc gọi tới

startTime

Date

Thời gian bắt đầu cuộc gọi

answerTime

Date

Thời gian bắt đầu chấp nhận cuộc gọi

endTime

Date

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

endCause

String

Nguyễn nhân kết thúc cuộc gọi.

Gồm:

BUSY: máy bận
NO_ANSWER: hết thời gian đổ chuông
TRIAL_REJECTION: khi gọi tới số điện thoại chưa gọi vào số tổng tài (với tài khoản OMI Trial)
LIMITATION_DECLINE: quá thời lượng cho phép gọi ra
ALLOTTED_TIMEOUT: Cuộc gọi đạt giới hạn thời lượng

uuid

String

Transaction ID của cuộc gọi

duration

Number

Thời gian gọi giữa 2 người sau khi chấp nhận cuộc gọi cho tới khi cuộc gọi kết thúc

durationTxt

String

Thời gian gọi giữa 2 người sau khi chấp nhận cuộc gọi cho tới khi cuộc gọi kết thúc và đã được định dạng theo thời gian: 00:00

totalDuration

Number

Tổng thời gian từ khi bắt đầu thực hiện/nhận cuộc gọi tới khi kết thúc

ping

Object

Dữ liệu về trạng thái tín hiệu của cuộc gọi

isAccepted

Boolean

Trạng thái đã nhận cuộc gọi giữa hai bên

Cấu hình và Sự kiện

config.theme

String

Giao diện dialog cuộc gọi (nếu để trống thì sẽ không có giao diện). Hoặc một trong các giá trị sau

default : Giao diện (như ảnh ở trên)

config.debug

Boolean

Bật tắt chức năng log các sự kiện của SDK.

Mặc định: false

config.busy

Boolean

Trạng thái cho phép thực hiện cuộc gọi ra, nhưng sẽ tự động từ chối tất cả các cuộc gọi tới

config.language

String

Ngôn ngữ hiển thị dialog cuộc gọi mặc định của SDK.

Gồm: "vi" : Tiếng Việt (default) "en" : Tiếng anh

config.ringtoneVolume

Number

Âm lượng chuông, khi khách gọi tới (từ 0 - 1)

config.options

Object

hideCallButton: Boolean Ẩn hiện nút gọi
showContactLoading:Boolean Ẩn hiện loading vị trí tên của người gọi trong dialog cuộc gọi
maskedPhoneNumberFormat: Array tùy chỉnh format ẩn số điện thoại ở dialog gọi. E.g.: - ['start', 4, 'x'] => xxxx749346 - ['end', 3, 'x'] => 0394749xxx
draggable: Boolean để cho phép để thay đổi vị trí của nút bật tắt dialog call và dialog cuộc gọi
btnCloseText: String để tuỳ chỉnh nội dung chữ của nút đóng và lưu lại cuộc gọi nếu có hiển thị input note hoặc custom forms
showNoteInput: Boolean | { required: Boolean } hiển thị input note mặc định và nút "Đóng và lưu lại"
showTagField: Boolean | { required: Boolean } hiển thị field chọn tag ở form data bên phải dialog call, nếu trước đó mảng forms chưa có field id = 'tag'
showInfoLastCall: Boolean | { overrideContact: Boolean } hiển thị thời gian và note gần nhất với remoteCall đang gọi, hiện thị avatar và name của contact tương ứng nếu có

config.forms

Array [Object]

Mảng form data tuỳ chỉnh.

id: ID định danh của field input
label: Tên của field input
plh: placeholder của input
multiline: hiện thị input dạng textarea
required: thêm dấu * bên cạnh tên của input và chặn đóng dialog call khi chưa nhập input
className: class tuỳ chỉnh truyền vào div ngoài cùng của field input
height: chiều cao tuỳ chỉnh cho input multiline

*Ví dụ: {

id: 'address', => bắt buộc label: 'Địa chỉ', plh: 'Nhập địa chỉ', multiline: true/fasle, required: true/fasle, className: String, height: '200px', }

config.classes

Object

btnToggle:String được truyền vào thuộc tính class của div ngoài cùng của button đóng mở UI cuộc gọi
dialog:String được truyền vào thuộc tính class của div ngoài cùng của dialog UI cuộc gọi

config.styles

Object

btnToggle:Object được truyền vào thuộc tính style của div ngoài cùng của button đóng mở UI cuộc gọi
dialog:Object được truyền vào thuộc tính style của div ngoài cùng của dialog UI cuộc gọi

E.g. Object style: { 'background-color': 'blue', justifyContent: 'center', color: 'red' },

config.callbacks

Object

Object chứa các event function callback

callbacks.register

Function

Sự kiện xảy ra khi trạng thái kết nối tổng đài thay đổi

callbacks.connecting

Function

Sự kiện xảy ra khi bắt đầu thực hiện cuộc gọi ra

callbacks.invite

Function

Sự kiện xảy ra khi có cuộc gọi tới

callbacks.inviteRejected

Function

Sự kiện xảy ra khi có cuộc gọi tới, nhưng bị tự động từ chối

callbacks.ringing

Function

Sự kiện xảy ra khi cuộc gọi ra bắt đầu đổ chuông

callbacks.accepted

Function

Sự kiện xảy ra khi cuộc gọi vừa được chấp nhận

callbacks.incall

Function

Sự kiện xảy ra mỗi 1 giây sau khi cuộc gọi đã được chấp nhận

callbacks.acceptedByOther

Function

Sự kiện dùng để kiểm tra xem cuộc gọi bị kết thúc, đã được chấp nhận ở thiết bị khác hay không

callbacks.ended

Function

Sự kiện xảy ra khi cuộc gọi kết thúc

callbacks.holdChanged

Function

Sự kiện xảy ra khi trạng thái giữ cuộc gọi thay đổi

callbacks.saveCallInfo

Function

Sự kiện xảy ra khi cuộc gọi đã có đổ chuông hoặc cuộc gọi tới, khi user có nhập note input mặc định hoặc form input custom

callbacks.infoLastCall

Function

Sự kiện xảy ra khi có bật options.showInfoLastCall và SDK có get được data cho số điện thoại đang gọi

Previousv3 Changelog Nextv2 Changelog

Last updated 12 days ago

<body>  <script omi-sdk type="text/javascript" src="https://cdn.omicrm.com/sdk/2.0.0/sdk.min.js"></script> <script> document.addEventListener('DOMContentLoaded', () => { // Ví dụ về một số config có thể dùng khi init SDK let config = { theme: 'default', callbacks: { register: (data) => { // Sự kiện xảy ra khi trạng thái kết nối tổng đài thay đổi console.log('register:', data); }, connecting: (data) => { // Sự kiện xảy ra khi bắt đầu thực hiện cuộc gọi ra console.log('connecting:', data); }, invite: (data) => { // Sự kiện xảy ra khi có cuộc gọi tới console.log('invite:', data); }, inviteRejected: (data) => { // Sự kiện xảy ra khi có cuộc gọi tới, nhưng bị tự động từ chối // trong khi đang diễn ra một cuộc gọi khác console.log('inviteRejected:', data); }, ringing: (data) => { // Sự kiện xảy ra khi cuộc gọi ra bắt đầu đổ chuông console.log('ringing:', data); }, accepted: (data) => { // Sự kiện xảy ra khi cuộc gọi vừa được chấp nhận console.log('accepted:', data); }, incall: (data) => { // Sự kiện xảy ra mỗi 1 giây sau khi cuộc gọi đã được chấp nhận console.log('incall:', data); }, acceptedByOther: (data) => { // Sự kiện dùng để kiểm tra xem cuộc gọi bị kết thúc // đã được chấp nhận ở thiết bị khác hay không console.log('acceptedByOther:', data); }, ended: (data) => { // Sự kiện xảy ra khi cuộc gọi kết thúc console.log('ended:', data); }, holdChanged: (status) => { // Sự kiện xảy ra khi trạng thái giữ cuộc gọi thay đổi console.log('on hold:', status); }, saveCallInfo: (data) => { // let { callId, note, ...formData } = data; // Sự kiện xảy ra khi cuộc gọi đã có đổ chuông hoặc cuộc gọi tới, khi user có nhập note input mặc định hoặc form input custom console.log('on save call info:', data); }, infoLastCall: (data) => { // Sự kiện xảy ra khi có bật options.showInfoLastCall và SDK có get được data cho số điện thoại đang gọi console.log('on found info last call:', data); }, } }; omiSDK.init(config, () => { // Truy cập OMICall // Vào menu : Cấu hình >> Tổng đài >> Số nội bộ // Mở chi tiết 1 số nội bộ để lấy thông tin // omiSDK.register({ // domain: 'abc', // username: '100', // password: '123456' // }); omiSDK.register({ domain: '', username: '', // tương đương trường "sip_user" trong thông tin số nội bộ password: '' }); }); // Cách khác để khai báo các SDK events: // omiSDK.on('register', (data) => { // // Sự kiện xảy ra khi trạng thái kết nối tổng đài thay đổi // console.log('register:', data); // }); // Cách khác để huỷ khai báo các SDK events: // omiSDK.off('register'); }); </script> </body>