v3 Integration
OMICallSDK: phiên bản SDK thứ 3 dành cho trình duyệt của OMICall, áp dụng mọi công nghệ mới nhất và hầu hết tính năng hiện có của OMICall SaaS, đem lại hiệu năng và chất lượng cuộc gọi tốt nhất.
Giới thiệu
- Sử dụng Webpack và TailwindCSS để tối ưu kích thước tập tin SDK cần nhúng - Áp dụng Vanilla JS để xử lý hiển thị lẫn tính năng, đem lại hiệu năng tốt nhất - Tự động giữ kết nối với tổng đài mỗi khi trạng thái kết nối mạng thay đổi - Tính điểm chất lượng tín hiệu của cuộc gọi realtime
Tích hợp
Example
Bên trên là code mẫu luồng tích hợp và sử dụng SDK với UI mặc định.
Nhúng script
Cách 1: thông qua CDN, khai báo thẻ <script>
<body>
<!-- Your app HTML -->
<script type="text/javascript" src="https://cdn.omicrm.com/sdk/web/{{version}}/core.min.js"></script>
</body>
Để lấy thông tin {{version}}, xem tại: Web SDK hoặc v3 Changelog
Cách 2: Thông qua
npm
: comming soon...
Khởi tạo
Sau khi script core.min.js
được load xong, sẽ có thêm biến global window.OMICallSDK
OMICallSDK
: biến global
chính của call SDK, quản lý kết nối tới tổng đài và xử lý các sự kiện của cuộc gọi.
OMICallUI
: biến global
khi sử dụng UI mặc định của SDK, có một số method để chủ động tương tác với UI mặc định.
type UIConfigs = {
/**
* toggleDial: trạng thái hiển thị nút mở giao diện nhập số gọi ra
* default: 'show'
*/
toggleDial?: 'show' | 'hide';
/**
* dialPosition: vị trí hiển thị nút mở giao diện nhập số gọi ra
* default: 'right'
*/
dialPosition?: 'left' | 'right';
/**
* theme: màu sắc của giao diện SDK
*/
theme?: {
white: '#ffffff';
black: '#000000';
primary: '#1e3150';
info: '#00b1ff';
success: '#56cc6e';
warning: '#fea220';
error: '#ff5955';
pink: '#e82a8f';
purple: '#a540b8';
blue: '#57bfdb';
};
/**
* cấu hình tự động hiển thị cuộc gọi mới ở chế độ thu gọn
* áp dụng cả cuộc gọi ra lẫn gọi vào
* default: false
*/
minimizeNewCall?: boolean;
};
type CtaButtonOnClick = (callData: CallData) => void;
type CtaButton = {
action: string;
label: string;
icon: string; // get icon `code` from `https://cdn.omicrm.com/common/icon/fluent-systems-filled/index.json`
onClick?: CtaButtonOnClick; // override callback chung cho riêng button này
};
type CallTab = {
id: string;
label: string;
/*
* Các cách để xử lý hiển thị nội dung tuỳ biến:
*
* #1: set trực tiếp HTML/CSS cần thiết
* tabNode.innerHTML = '<div>your HTML/CSS</div>';
*
* #2: với React 18+, dùng thư viện react-dom/client
* createRoot(tabNode).render(<YourComponent />);
*
* #3: các framework khác tương tự ReactJS
*/
render: (callData: CallData, tabNode: HTMLDivElement, tabDetail: { id: string; label: string }) => void;
};
type SdkConfigs = {
/**
* lng: ngôn ngữ hiển thị trên UI
* default: 'vi'
*/
lng?: 'vi' | 'en' | 'km';
/**
* ui: cấu hình giao diện mặc định của SDK
*/
ui?: UIConfigs;
/**
* control ringtone volume
* default: 1
*/
ringtoneVolume?: number /* 0 -> 1 */;
/**
* control phone number masking
*/
phoneMasked?: {
enable: boolean;
/**
* length: độ dài cho phép hiển thị số
*/
len: number;
/**
* character: *, #, x, ✨, ...
*/
char: string;
/**
* ltr: left-to-right
*/
ltr: boolean;
};
/**
* show list of CTA buttons, under remote contact info of calling dialog
*/
ctaButtons?: {
unknown?: CtaButton[]; // show when `remoteContact` is null
exists?: CtaButton[]; // show when `remoteContact` is not null
base?: CtaButton[]; // always show these buttons
onClick?: CtaButtonOnClick; // callback chung cho tất cả cta button
};
/**
* thay thế UI "Thông tin cuộc gọi" bằng UI dạng tabs
* vẫn giữ lại giao diện cũ dưới dạng tab cuối cùng
*/
callTabs?: CallTab[];
/**
* your main app's root body element
* use for app need to passing a custom tab component into call dialog
* use this option if your component required `HOCs` or `Context Provider`
*/
rootBody?: HTMLElement;
/**
* custom search remote contact function
*/
searchRemoteContact?: (callData: CallData) => Promise<RemoteContact | null>;
};
const sdkConfigs = {
/* tuỳ chỉnh cấu hình */
};
const initSuccess: Boolean = await OMICallSDK.init(sdkConfigs as SdkConfigs);
if (!initSuccess) {
// nếu khởi tạo SDK có lỗi, không thực hiện register tổng đài
return;
}
Kết nối
type RegisterStatus = {
status: boolean;
error?: string;
};
/* Thông tin số nội bộ */
const sipRealm = 'demo01'; // domain tổng đài
const sipUser = '100'; // số nội bộ
const sipPassword = 'ABC123!@#'; // mật khẩu của số nội bộ
// Để kết nối tới tổng đài
const registerStatus: RegisterStatus = await OMICallSDK.register({
sipRealm,
sipUser,
sipPassword,
});
// Để ngắt kết nối tới tổng đài
OMICallSDK.unregister();
Để lấy thông tin số nội bộ:
Cách 1: dùng API public tại Danh sách SỐ NỘI BỘ
Cách 2: truy cập màn hình Cấu hình ▸ Tổng đài ▸ Số nội bộ trong website OMICall
Methods
Để gọi nhanh một số sđt, sử dụng function:
type SipNumber = {
number: string;
};
type RemoteContact = {
name: string;
avatar?: string; // URL | Base64
gender?: 'male' | 'female' | 'other';
};
type MakeCallOptions = {
isVideo?: boolean;
sipNumber?: SipNumber;
remoteContact?: RemoteContact;
/* userData: custom data, will be attach to call history */
userData?: string;
};
const remoteNumber: string = ''; /* phone number or Zalo User ID */
const options: MakeCallOptions | null = null;
OMICallSDK.makeCall(remoteNumber, options);
Để mở/ đóng cửa sổ nhập số gọi ra của UI mặc định:
OMICallUI.toggleDial();
Sự kiện & Dữ liệu
/*
Một eventName có thể đăng ký bởi nhiều callback function, vậy nên khi huỷ đăng ký,
cần truyền đúng eventCallback đã đăng ký trước đó
*/
OMICallSDK.on(eventName, eventCallback);
OMICallSDK.off(eventName, eventCallback);
type EventName =
// event trạng thái kết nối tổng đài, callback data: `type RegisterData`
'register'
// các events của cuộc gọi, callback data: `type CallData`
| 'connecting' // khi cuộc gọi ra bắt đầu kết nối
| 'ringing' // khi cuộc gọi bắt đầu đổ chuông
| 'on_ringing' // mỗi giây, khi đang đổ chuông
| 'accepted' // khi cuộc gọi được bắt máy
| 'on_calling' // mỗi giây, khi đang trong cuộc gọi đã bắt máy
| 'set_sip_number' // khi có được số hotline đang dùng để gọi ra
| 'ended' // khi cuộc gọi kết thúc
;
type RegisterData = {
status: 'connecting' | 'connected' | 'disconnect';
name: string; // đa ngôn ngữ của trạng thái kết nối
};
type CallData = {
uid: string; // UUID tự sinh
uuid?: string; // UUID từ tổng đài
state: 'connecting' | 'ringing' | 'accepted' | 'ended'; // trạng thái hiện tại
direction: 'outbound' | 'inbound';
isVideo: boolean;
isOutbound: boolean;
isInternal: boolean;
sipNumber?: SipNumber;
remoteContact?: RemoteContact;
remoteNumber: string;
displayNumber: string; // áp dụng theo phân quyền ẩn sđt
streams: Record<'local' | 'remote', MediaStream>;
players: Record<'local' | 'remote', HTMLVideoElement>;
startTs: number; // thời gian bắt đầu cuộc gọi, Timestamp
startAt: string; // thời gian bắt đầu cuộc gọi, format: HH:mm:ss
held: boolean; // trạng thái giữ cuộc gọi
audio: boolean; // trạng thái bật/ tắt microphone
video: boolean; // trạng thái bật/ tắt camera
ua: string; // window.navigator.userAgent
devices: {
audio: boolean;
video: boolean;
}; // trạng thái khả dụng của thiết bị microphone/ camera
rtcpStat: any; // thống kê chất lượng kết nối của cuộc gọi
rejectCode?: string; // mã lỗi từ tổng đài
ringingDuration: CallDuration;
callingDuration: CallDuration;
userData?: string;
// các function để tương tác với cuộc gọi
end: () => void; // hành động chung để kết thúc cuộc gọi
decline: () => void; // hoàn toàn kết thúc cuộc gọi tới, không tiếp tục phân bổ cuộc gọi
accept: () => void;
mute: (cb?: () => boolean) => void; // bật/ tắt microphone, `cb` trả về trạng thái mới
camera: (cb?: () => boolean) => void; // bật/ tắt camera, `cb` trả về trạng thái mới
hold: (cb?: () => boolean) => void; // bật/ tắt giữ cuộc gọi, `cb` trả về trạng thái mới
dtmf: (tone: string) => void; // gửi tương tác bấm phím, mỗi `tone` là 1 ký tự [0-9*#]
transfer: (target: string) => void; // target: số nội bộ, nhóm nội bộ, nhóm bên ngoài, tương tác bấm phím
save: (
info: {
note?: string;
tags?: string[];
},
onSave: () => void,
onFinish: () => boolean
) => void; // gọi function này, khi bạn muốn lưu note hoặc tags vào OMICall
/**
* cho phép chủ động trigger việc phóng to/ thu nhỏ UI của call dialog
* @param getCustomPosition: cho phép tuỳ biến vị trí tiếp theo sẽ hiển thị, sau khi cập nhật kích thước UI
*/
minimize: (getCustomPosition?: (data: { width: number; height: number }) => { x: number; y: number }) => void;
};
type SipNumber = {
// thông tin luôn có
number: string;
/*
Các data khác chỉ có khi gọi bằng UI mặc định
Cấu trúc riêng của OMICall, có thể thay đổi trong tương lai
Không khuyến khích dử sụng
*/
};
type RemoteContact = {
name: string;
avatar?: string; // URL | Base64
gender?: 'male' | 'female' | 'other';
};
type CallDuration = {
value: number; // 0
text: string; // '00:00'
};
Giao diện tuỳ biến
Khi sử dụng SDK cho giao diện tuỳ biến, hãy đảm bảo thực hiện đủ các nghiệp vụ bên dưới:
1. Sau khi đã đảm bảo SDK đã được tải, hãy Khởi tạo SDK
2. Kết nối tới tổng đài
3. Đăng ký các sự kiện kết nối và trạng thái của cuộc gọi theo Sự kiện & Dữ liệu
4. Cache lại giá trị Object
CallData
trong event callback phía dưới:
- Event connecting
cho cuộc gọi ra
- Event ringing
cho cuộc gọi đến
5. Render 2 thẻ <video />
ứng với 2 người trong cuộc gọi (nên để 2 thẻ này là children của dialog cuộc gọi tuỳ biến):
<video id="${callData.uid}-local" style="display:none" playsinline autoplay hidden mute />
<video id="${callData.uid}-remote" style="display:none" playsinline autoplay hidden />
6. Dùng các method trong CallData
để:
- Nhận cuộc gọi: callData.accept();
- Từ chối hoặc kết thúc cuộc gọi: callData.end();
- Bật/ Tắt microphone: callData.mute(cb);
- Bật/ Tắt camera: callData.camera(cb);
- Bật/ Tắt giữ cuộc gọi: callData.hold(cb);
- Gửi tương tác bấm phím: callData.dtmf(tone);
- Chuyển tiếp cuộc gọi: callData.transfer();
- Lưu ghi chú hoặc Tag vào OMICall: callData.save({ note:'', tags: ['test'] });
Giao diện mặc định
Screenshots











Tính năng
Nút ẩn/ hiện cửa sổ gọi ra
Đổi được vị trí hiển thị:
ui.dialPosition = left | right
Có thể ẩn được nút ẩn/ hiện:
ui.toggleDial = show | hiden
Xem được trạng thái kết nối tổng đài
Đổi được trạng thái kết nối tổng đài
Giao diện cửa sổ gọi ra Tái hiện toàn bộ giao diện gọi ra của web OMICall. Tuỳ biến một số sang diện danh sách và lịch sử cuộc gọi dành riêng cho SDK
Đổi được vị trí hiển thị:
ui.dialPosition = left | right
Giao diện bàn phím số
Giao diện lịch sử cuộc gọi: - Tối ưu cho giao diện nhỏ gọn của SDK từ phiên bản web - Hiển thị tối đa 50 cuộc gọi trong 7 ngày gần nhất - Hỗ trợ tìm kiếm theo số điện thoại hoặc tên người gọi - Hỗ trợ nghe lại file ghi âm của cuộc gọi - Bấm để nhập nhanh vào ô số cần gọi ra
Giao diện danh sách số nội bộ: - Hiển thị tất cả số nội bộ của doanh nghiệp - Tự động hiển thị kết quả trong khi nhập tìm kiếm - Bấm để nhập nhanh vào ô số cần gọi ra
Giao diện danh sách nhóm nội bộ: - Hiển thị tất cả nhóm nội bộ của doanh nghiệp - Tự động hiển thị kết quả trong khi nhập tìm kiếm - Bấm để nhập nhanh vào ô số cần gọi ra
Giao diện danh sách nhóm bên ngoài: - Hiển thị tất cả nhóm nội bộ của doanh nghiệp - Tự động hiển thị kết quả trong khi nhập tìm kiếm - Bấm để nhập nhanh vào ô số cần gọi ra
Giao diện danh sách tương tác bấm phím: - Hiển thị tất cả tương tác bấm phím của doanh nghiệp - Tự động hiển thị kết quả trong khi nhập tìm kiếm - Bấm để nhập nhanh vào ô số cần gọi ra
Cấu hình đầu số gọi ra: - Hiển thị đầu số gọi ra hiện tại của số nội bộ - Cho phép đổi "tạm thời" số dùng để gọi ra trong phiên kết nối này
Cấu hình cuộc gọi cá nhân: - Xem được các cấu hình cuộc gọi đang áp dụng của số nội bộ: + Remote Call: Cuộc gọi sẽ thực hiện trực tiếp trên IP Phone, Softphone - Cập nhật "tạm thời" cấu hình "Remote Call" cho các cuộc gọi của phiên kết nối này
Hỗ trợ cuộc gọi Audio
Hỗ trợ cuộc gọi Video
Hỗ trợ gọi ra bằng đầu số ZCC: có đủ UX/UI cấp quyền và kiểm tra trạng thái được phép gọi tới sđt của tài khoản Zalo
Hỗ trợ hiển thị nhiều dialog cuộc gọi đồng thời
Hỗ trợ di chuyển vị trí của dialog cuộc gọi
Giao diện trong cuộc gọi
- Tái hiện toàn bộ* giao diện và tính năng trong cuộc gọi của web OMICall *Ngoại trừ duy nhất tính năng "LazyCall" - Tối ưu giao diện gọi Video. Hỗ trợ thay đổi giao diện khi camera của người gọi xoay hướng - Tối ưu giao diện gom nhóm khi có nhiều của sổ cuộc gọi đang hiển thị - Áp dụng đầy đủ phân quyền và cấu hình cuộc gọi như ở web OMICall
Last updated
Was this helpful?