Web Chat SDK

Nhúng khung chat vào website: khách truy cập nhắn tin ngay trên trang, tin hiện trong Hộp thư của SieuTroly như các kênh khác; nhân viên (hoặc Trợ lý AI đã bật tự trả lời cho kênh này) trả lời và khách thấy ngay.

SDK là một tệp JavaScript thuần, không phụ thuộc thư viện nào, giao diện nằm trong Shadow DOM nên không đụng CSS của website.

1. Bắt đầu nhanh

1. Vào Channels → Kênh Chat → Thêm kênh → Web Chat (nhúng website), chỉnh giao diện, điền website được phép rồi lưu.
2. Hộp Mã nhúng hiện ra (mở lại bằng nút Mã nhúng trên thẻ kênh). Dán đoạn mã vào website, trước thẻ </body>:

<script src="https://api.sieutroly.ai/webchat/sdk.js" data-key="wc_xxxxxxxxxxxxxxxxxxxxxxxx" async></script>

3. Mở website, bấm biểu tượng chat ở góc màn hình và nhắn thử. Hoặc dùng nút Dùng thử (trang /webchat/demo?key=…).

SDK tự dùng đúng địa chỉ nơi nó được tải về (https://api.sieutroly.ai), không cần cấu hình thêm.

2. Tùy chọn

Có hai cách: thuộc tính data-* trên thẻ script, hoặc gọi SieuTrolyChat.init({...}). Tùy chọn ở đây ưu tiên hơn cấu hình trong trang quản trị.

init()	data-*	Ý nghĩa
key	data-key	Mã kênh wc_… (bắt buộc)
api	data-api	Địa chỉ backend (mặc định lấy từ địa chỉ tải SDK)
lang	data-lang	vi hoặc en
color	data-color	Màu chủ đạo, vd #0ea5e9
position	data-position	left / right
title	data-title	Tiêu đề khung chat
hideLauncher	data-hide-launcher="true"	Ẩn nút tròn (tự mở bằng open())
autoOpen	data-auto-open="true"	Mở khung chat ngay khi tải trang

Các thiết lập còn lại (lời chào, dòng phụ, form thu thập thông tin, tự mở sau N giây, chữ gợi ý cạnh nút…) chỉnh trong trang quản trị và có hiệu lực ngay, không cần sửa website.

3. JavaScript API

SieuTrolyChat.init({ key: 'wc_…', lang: 'vi' });   // khi không dùng data-key
SieuTrolyChat.open();      SieuTrolyChat.close();   SieuTrolyChat.toggle();
SieuTrolyChat.isOpen();    // boolean
SieuTrolyChat.unread();    // số tin chưa đọc khi khung đang đóng
SieuTrolyChat.identify({ name: 'Nguyễn Văn A', phone: '0901234567', email: '[email protected]' });
SieuTrolyChat.on('message', function (m) { console.log('Nhân viên:', m.text); });
SieuTrolyChat.off('message', handler);
SieuTrolyChat.destroy();   // gỡ widget (vd khi khách đăng xuất)

• identify: dùng khi website đã biết khách là ai (đã đăng nhập). Thông tin được gắn vào hồ sơ khách trong Hộp thư (gửi kèm tin đầu tiên, hoặc cập nhật ngay nếu khách đã chat). Nếu đã điền, form "thu thập thông tin" sẽ không hỏi lại.
• Sự kiện: ready (đã tải xong), open, close, message (có tin mới từ nhân viên), unread (số tin chưa đọc đổi), error.

Website dùng React / Vue / Next.js / SPA

Tải SDK một lần rồi gọi API; nhớ destroy() khi gỡ component.

// React
import { useEffect } from 'react';
export function ChatWidget({ user }) {
  useEffect(() => {
    const s = document.createElement('script');
    s.src = 'https://api.sieutroly.ai/webchat/sdk.js'; s.async = true;
    s.onload = () => {
      window.SieuTrolyChat.init({ key: 'wc_…' });
      if (user) window.SieuTrolyChat.identify({ name: user.name, email: user.email });
    };
    document.body.appendChild(s);
    return () => { window.SieuTrolyChat?.destroy(); s.remove(); };
  }, [user]);
  return null;
}

4. Hoạt động và bảo mật

• Khách và hội thoại: mỗi trình duyệt có một mã khách ẩn danh lưu trong localStorage; quay lại sau vẫn thấy lịch sử chat. Khách chỉ trở thành Liên hệ trong Hộp thư khi gửi tin đầu tiên (chỉ xem trang không tạo gì).
• Giới hạn website: ô Chỉ cho phép các website trong cấu hình kênh. Để trống = nơi nào có mã kênh cũng nhúng được; nên điền (hỗ trợ *.example.com). Mã kênh wc_… là công khai (nằm trong mã nhúng), nên đây là lớp bảo vệ chính.
• Phiên chat: mỗi phiên có token ký HMAC riêng của kênh, hết hạn sau 30 ngày; token giả/sửa bị từ chối.
• Giới hạn tốc độ & độ dài: tối đa 30 tin/phút/khách, 2.000 ký tự/tin; vượt quá sẽ báo "gửi quá nhanh".
• An toàn nội dung: tin nhắn hiển thị dạng văn bản (không chạy HTML/JS); chỉ liên kết http(s) được bấm, mở tab mới với rel="noopener noreferrer nofollow".
• Quyền riêng tư: SDK không dùng cookie của website; thông tin trang (URL) được lưu kèm tin đầu tiên để nhân viên biết khách đang xem trang nào.
• CSP: nếu website dùng Content-Security-Policy, cần cho phép script-src và connect-src tới https://api.sieutroly.ai. SDK dựng stylesheet bằng JavaScript nên không cần style-src 'unsafe-inline' trên trình duyệt hỗ trợ adoptedStyleSheets.

5. Tính năng hiện có / chưa có

Có: chat văn bản, nhận tin của nhân viên gần như tức thì (long-poll), số tin chưa đọc, form thu thập thông tin trước khi chat, tiếng Việt/English, giao diện responsive (toàn màn hình trên điện thoại), thử gửi lại khi lỗi mạng, tự kết nối lại.

Chưa có (có thể bổ sung): gửi ảnh/tệp từ phía khách, chỉ báo "đang soạn tin", âm thanh thông báo, tải lên avatar nhân viên, giờ làm việc/tin nhắn ngoài giờ.

6. Giao thức HTTP (cho ai muốn tự dựng giao diện)

Mọi endpoint ở https://api.sieutroly.ai/webchat/v1, JSON, CORS mở (quyền do danh sách website của kênh quyết định).

Endpoint	Mô tả
GET /config?key=wc_…	Cấu hình giao diện (tiêu đề, màu, lời chào, form…)
POST /session {key, visitor_id?}	Tạo phiên → {visitor_id, token, messages[], cursor}; không tạo liên hệ
GET /messages?after=<ISO>&wait=<giây≤25>	Lấy tin mới (long-poll). Header Authorization: Bearer <token>
POST /messages {text, client_id, profile?, page?}	Gửi tin; client_id giúp chống gửi trùng khi thử lại
POST /profile {name?, phone?, email?}	Cập nhật thông tin khách

Lỗi trả {error, message}: unknown_key (404), origin_not_allowed/disabled (403), invalid_token (401), profile_required (400, kèm fields), rate_limited (429), too_long/empty (400).

7. Xử lý sự cố

Triệu chứng	Nguyên nhân thường gặp
Không thấy nút chat	Mã kênh sai; kênh đang tắt; tên miền chưa nằm trong danh sách được phép (xem tab Network: origin_not_allowed); CSP chặn script
Gửi tin báo lỗi	Mất mạng; gửi quá nhanh (429); thiếu thông tin bắt buộc ở form
Nhân viên trả lời nhưng khách không thấy	Kênh đang tắt; token hết hạn (SDK tự tạo phiên mới); kiểm tra GET /messages có bị chặn bởi proxy/CDN không (cần cho phép request giữ tối đa ~25 giây)