Module 04: Chatbot Widget (Embed)
Module 04 • CRM & Web Embed SDK
SDK Quick Start & Chi Tiết API window.pcw
Tài liệu này cung cấp hướng dẫn tích hợp chi tiết và đặc tả toàn bộ các phương thức điều khiển của đối tượng toàn cục window.pcw (Pango Chat Widget) dành cho các kỹ sư Frontend (JavaScript, TypeScript, React, Next.js, Vue, Angular).
1. Quick Start: Nhúng SDK Script
Thêm thẻ <script> vào cuối thẻ <body> của ứng dụng web. Widget được đóng gói theo chuẩn ES Module hiện đại:
Môi Trường Staging:
<!-- Pango Chat Widget SDK [Staging] -->
<script
type="module"
src="https://pango-chat-widget.pages.dev/widget.js"
></script>Môi Trường Production:
<!-- Pango Chat Widget SDK [Production] -->
<script
type="module"
src="https://cps-ai-widget.mydatalakes.com/widget.js"
></script>Tự Động Khởi Tạo (Auto-mount)
Trên một số phiên bản đóng gói theo tên miền riêng của đối tác, script sẽ tự động tạo bong bóng chat tròn ở góc màn hình ngay khi tải xong mà không cần gọi hàm nào khác. Để kiểm soát chủ động chu trình khởi tạo, hãy sử dụng các hàm API dưới đây.
2. Bảng Phương Thức Điều Khiển window.pcw
Sau khi script tải xong, đối tượng window.pcw xuất hiện trên phạm vi toàn cục với các phương thức sau:
Sơ Đồ Trực Quan (Interactive Flowchart)
Đang tạo biểu đồ trực quan...
2.1 init()
- Mô tả: Khởi tạo cấu hình widget và đưa thẻ Iframe vào cây DOM của trang web mẹ.
- Cú pháp:
window.pcw.init() - Ví dụ:
// Gọi sau khi trang web tải xong hoặc khi component được mount
window.addEventListener('DOMContentLoaded', () => {
if (window.pcw) {
window.pcw.init();
}
});2.2 destroy()
- Mô tả: Gỡ bỏ hoàn toàn Iframe khỏi DOM và hủy toàn bộ các trình lắng nghe sự kiện (
postMessagelisteners) để giải phóng bộ nhớ. Thường dùng khi người dùng đăng xuất hoặc chuyển trang trong ứng dụng SPA. - Cú pháp:
window.pcw.destroy()
2.3 setPayload(payload)
- Mô tả: Đẩy dữ liệu ngữ cảnh (Context) từ Host App vào Widget. Dữ liệu này sẽ được đính kèm vào System Context khi Chatbot xử lý câu hỏi.
- Cú pháp:
window.pcw.setPayload(payloadObject) - Hỗ trợ 2 cơ chế cập nhật:
- Full Payload Update: Cập nhật toàn bộ thông tin tài khoản, phòng chat và dữ liệu nghiệp vụ:
window.pcw.setPayload({
conversation: { conversationId: "CONV_987654" },
account: { id: 101, username: "agent_support", mainEmail: "support@brand.com" },
admin: { id: "ADMIN_01", username: "Manager QL" },
userInfo: { id: "CUST_555", username: "Trần Thị B", mainPhone: "0901234567" }
});- Partial Payload Update: Cập nhật từng khóa riêng lẻ khi có thay đổi trạng thái (ví dụ khi người dùng đổi phòng chat):
// Chỉ cập nhật lại ID cuộc hội thoại mới
window.pcw.setPayload({
conversation: { conversationId: "CONV_NEW_ROOM_112" }
});2.4 open(), close(), toggle()
- Mô tả: Điều khiển từ xa trạng thái mở hoặc đóng của khung chat từ các nút bấm riêng trên giao diện của Host App (ví dụ: nút "Tư Vấn Cùng AI" trên thanh header).
- Cú pháp:
window.pcw.open(); // Mở bung cửa sổ chat
window.pcw.close(); // Thu nhỏ thành bong bóng chat nổi
window.pcw.toggle(); // Đảo ngược trạng thái hiện tại2.5 show(), hide()
- Mô tả: Ẩn hoặc hiện toàn bộ widget (tàng hình cả bong bóng chat nổi). Rất hữu ích khi bạn muốn ẩn widget trên một số trang nhạy cảm (như trang thanh toán, nhập mật khẩu) mà không cần xóa thẻ script.
- Cú pháp:
window.pcw.hide(); // Ẩn hoàn toàn khỏi màn hình
window.pcw.show(); // Hiển thị trở lại2.6 setPosition(position)
- Mô tả: Thay đổi góc neo hiển thị của widget trên màn hình theo thời gian thực.
- Tham số hợp lệ:
'bottom-right'(Góc dưới bên phải - Mặc định) hoặc'bottom-left'(Góc dưới bên trái). - Cú pháp:
window.pcw.setPosition('bottom-left');2.7 setOffset(x, y)
- Mô tả: Tinh chỉnh khoảng cách lệch khỏi mép màn hình (tính theo pixel) để tránh che khuất các nút điều hướng, nút gọi hotline hoặc thanh tác vụ quan trọng của Host App.
- Cú pháp:
window.pcw.setOffset(horizontalPx, verticalPx) - Ví dụ:
// Đẩy widget cách mép màn hình 40px chiều ngang và 60px chiều dọc
window.pcw.setOffset(40, 60);
// Khôi phục về vị trí mặc định (24px)
window.pcw.setOffset(24, 24);3. Trạng Thái Co Giãn & Responsive (Scale)
Widget tự động tối ưu hóa kích thước hiển thị dựa trên thiết bị và trạng thái đóng mở:
- Trạng thái đóng (Launcher Bubble): Iframe thu nhỏ kích thước còn 80x80px với nền trong suốt, chỉ hiển thị bong bóng chat nổi và huy hiệu thông báo.
- Trạng thái mở (Chat Drawer): Kích thước mở rộng thành 380x600px (hoặc 420x680px tùy cấu hình đối tác) ở góc phải màn hình desktop, và tự động chuyển sang chế độ toàn màn hình (
100dvh) trên thiết bị di động.
4. Chu Trình Vòng Đời Của Widget (Lifecycle)
Sơ Đồ Trực Quan (Interactive Flowchart)
Đang tạo biểu đồ trực quan...
5. Hỗ Trợ TypeScript Hoàn Chỉnh
Để tận hưởng tính năng tự động gợi ý code thông minh (IntelliSense) và kiểm tra kiểu dữ liệu trong các dự án React, Next.js, hoặc Vue, bạn chỉ cần tạo file khai báo kiểu sau:
global.d.ts:
export interface Conversation {
conversationId: string;
}
export interface Account {
id: number | string;
username: string;
mainEmail: string;
mainPhone?: string;
groupId?: number;
groupName?: string;
extraInfo?: Record<string, any>;
}
export interface Admin {
id: number | string;
username: string;
}
export interface UserInfo {
id: string;
username: string;
mainEmail?: string;
mainPhone?: string;
channelInfo?: string;
}
export interface LastTicket {
ticketId?: number;
ticketPriority?: string;
ticketSource?: string;
ticketStatus?: string;
ticketSubject?: string;
createdAt?: string;
updatedAt?: string;
}
export interface PangoWidgetPayload {
externalPrivateKey?: string;
conversation?: Conversation;
account?: Account;
admin?: Admin;
userInfo?: UserInfo;
lastTicket?: LastTicket;
}
export interface PangoChatWidgetAPI {
init: () => void;
destroy: () => void;
setPayload: (payload: Partial<PangoWidgetPayload>) => void;
open: () => void;
close: () => void;
toggle: () => void;
show: () => void;
hide: () => void;
setPosition: (pos: 'bottom-right' | 'bottom-left') => void;
setOffset: (x: number, y: number) => void;
}
declare global {
interface Window {
pcw?: PangoChatWidgetAPI;
}
}