Web SDK

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.

Version : 2.0.91
Release date : 02/11/2023
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

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

PreviousWebhookNextWeb SDK Changelog

Last updated