Widget Live Chat

Tích hợp widget trò chuyện vào website của bạn

Phiên bản: 1.0 | Ngày: 2025-10-19 | Trạng thái: ✅ Hoàn thành

---

📋 Tổng Quan

Live Chat Widget cho phép người dùng trò chuyện với chatbot ngay trên website. Hỗ trợ kết nối thời gian thực, streaming và tuỳ chỉnh giao diện.

---

🧩 Thành Phần & Kết Nối

• Kết nối: DDP/WebSocket tới server (tự động khôi phục phiên qua token)

• Thành phần UI: Launcher, Chat Window, Chat Entry

• Tính năng: streaming, ghi phiên, tự động reconnect

---

🛠️ Cài Đặt

Cách 1: Script Tag (Nhanh nhất)

1. Thêm script trước thẻ </body>

<script src="/path/to/your/widget-loader.js" defer></script>
<script>
  window.AIWidget && window.AIWidget.init({
    siteId: "YOUR_SITE_ID",
    chatbotId: "YOUR_CHATBOT_ID",
    themeColor: "#0F62FE",
    position: "bottom-right",
  });
</script>

1. Triển khai lên staging → test → production

Lưu ý: Thay /path/to/your/widget-loader.js bằng đường dẫn script thực tế của hệ thống bạn.

---

Cách 2: NPM Package

1. Cài package (nếu hệ thống cung cấp)

2. Import và khởi tạo trong app:

import { initAIWidget } from "@your-org/ai-widget";

initAIWidget({
  siteId: "YOUR_SITE_ID",
  chatbotId: "YOUR_CHATBOT_ID",
  themeColor: "#0F62FE",
  position: "bottom-right",
});

---

Cách 3: Tự Tích Hợp (Custom)

• Tự render Launcher/Window theo design của bạn

• Gọi API phiên chat: startSession, sendMessage, abortStream…

• Quản lý trạng thái, xử lý streaming theo nhu cầu

---

⚙️ Cấu Hình Phổ Biến

{
  "siteId": "YOUR_SITE_ID",
  "chatbotId": "YOUR_CHATBOT_ID",
  "themeColor": "#0F62FE",
  "position": "bottom-right",
  "iconSize": "medium",
  "launcherShape": "circle",
  "welcomeTitle": "Xin chào!",
  "welcomeMessage": "Tôi có thể giúp gì cho bạn?"
}

Tham khảo thêm: Widget Appearance (./06-WIDGET-APPEARANCE.md)

---

🧪 Kiểm Thử Trước Khi Deploy

• Hiển thị đúng trên desktop/tablet/mobile

• Streaming hoạt động mượt, không đứt quãng

• Chatbot trả lời đúng phạm vi

• Trích dẫn (nếu dùng KB) hiển thị chính xác

• Không chặn/che nội dung quan trọng của trang

---

🔐 Bảo Mật & Quyền Riêng Tư

• Sử dụng token phiên an toàn, auto-refresh nếu có

• Không log dữ liệu nhạy cảm trên client

• Tuân thủ chính sách quyền riêng tư của tổ chức

---

🧯 Khắc Phục Sự Cố

• Widget không hiển thị: kiểm tra script, vị trí chèn, lỗi console

• Không thể gửi tin: kiểm tra kết nối, token, hạn mức credits

• Streaming giật: kiểm tra mạng và server load

---

🔗 Tài Liệu Liên Quan

• Display Rules (./05-DISPLAY-RULES.md)

• Widget Appearance (./06-WIDGET-APPEARANCE.md)

• Chatbot Overview (./02-CHATBOT-OVERVIEW.md)

---

Phiên bản: 1.0 Cập nhật cuối: 2025-10-19 Trạng thái: ✅ Hoàn thành