Website Widget (Live Chat SDK)
Xem dạng Markdown
Kênh **Website** (`/{slug}/channels/website`) cho phép bạn tạo một hoặc nhiều khung chat trực tuyến (**Live Chat SDK**) nhúng trực tiếp vào website, kết nối với Bot AI và quản lý hội thoại tập trung trong Workspace.
:::note[Quyền truy cập]
- **Xem danh sách & chi tiết Widget**: Cần **`nick:read:all`** (hiển thị mục điều hướng khi có `nick:read:all`, `nick:connect` hoặc `nick:operate`).
- **Tạo Widget mới / Tải ảnh đại diện Widget**: Cần **`nick:connect`**.
- **Cập nhật cấu hình / Tạm dừng / Xoay vòng HMAC Secret**: Cần **`nick:operate`**.
- **Xóa Widget**: Cần **`nick:delete`**.
:::
## Tạo Website Widget mới
1. Truy cập **Kênh kết nối → Website** (`/{slug}/channels/website`) và nhấn **Thêm kênh** (mở trang `/{slug}/channels/website/new`).
2. Nhập tên kênh Website (tối đa 100 ký tự), cấu hình giao diện cơ bản và chọn Bot AI phụ trách.
3. Nhấn lưu để tạo Widget. Hệ thống sẽ sinh **`siteKey`** và **`hmacSecret`** riêng cho Widget và chuyển bạn tới trang quản lý chi tiết (`/{slug}/channels/website/{widgetId}`).
## 4 thẻ cấu hình trong không gian Widget
### 1. Widget (Giao diện & Nội dung)
Tùy chỉnh trực quan kèm khung **Xem trước tương tác (Live Preview)** ngay bên cạnh:
- **Màu sắc & Giao diện**: Màu chủ đạo (mã hex), chế độ màu (`light`, `dark`, `system`), phông chữ (`System`, `Inter`, `Roboto`, `Be Vietnam Pro`, `Plus Jakarta Sans`, `Nunito`, `Montserrat`, `Open Sans`), độ bo góc (`sharp`, `rounded`, `pill`) và kích thước cửa sổ (`compact` 350×480, `default` 390×560, `large` 430×640).
- **Vị trí & Hiển thị**: Góc dưới phải (`bottom-right`) hoặc dưới trái (`bottom-left`), khoảng cách lề X/Y (`0–200px`), kích thước nút mở chat (`36–96px`) và thời gian tự động mở (`1–300` giây, tùy chọn).
- **Nội dung chào mừng**: Tiêu đề khung chat (tối đa 80 ký tự), phụ đề trạng thái (tối đa 120 ký tự), ảnh đại diện (tối đa **2 MB**), lời chào mở đầu (tối đa 500 ký tự), văn bản gợi ý ô nhập (tối đa 80 ký tự) và tối đa **4 câu hỏi gợi ý (Quick Replies)** (mỗi câu tối đa 60 ký tự).
- **Biểu mẫu trước khi chat (Pre-chat Form)**: Khi bật, khách truy cập cần nhập **Họ tên** và **Số điện thoại** (tùy chọn yêu cầu thêm **Email**) trước khi bắt đầu trò chuyện.
### 2. Hội thoại (Conversations)
- Theo dõi và chuyển đổi trạng thái hoạt động của Widget giữa **`CONNECTED`** (đang hoạt động) và **`PAUSED`** (tạm dừng).
- Chọn **Bot AI** phụ trách và bật/tắt chế độ AI tự động trả lời cho Widget.
### 3. Cài đặt (Install)
Nhúng đoạn mã SDK trước thẻ đóng `</body>` trên website của bạn:
```html
<script
src="https://<domain-omnybot>/sdk/v1/widget.iife.js"
data-site-key="<SITE_KEY>"
async
></script>
```
Trang cài đặt cung cấp sẵn mẫu mã cho 7 nền tảng: **HTML Snippet**, **React / Next.js**, **Angular**, **Vue**, **WordPress**, **Google Tag Manager (GTM)** và **Shopify**, với hai chế độ:
- **Khách ẩn danh (Anonymous)**: Chỉ cần nhúng thẻ `<script>` cơ bản.
- **Khách đã đăng nhập (Logged-in)**: Gọi `window.OmnyBot("identify", { externalId, name, phone, email, hmac })` để đồng bộ danh tính khách hàng từ hệ thống của bạn.
### 4. Bảo mật (Security)
- **Domain được phép nhúng (`allowedDomains`)**: Nhập tối đa **20 tên miền** (hỗ trợ wildcard như `*.example.com`). Nếu để trống, Widget chấp nhận mọi tên miền `http/https`.
- **Cho phép `localhost`**: Bật khi cần thử nghiệm nhúng trên môi trường phát triển cục bộ (`localhost`, `127.0.0.1`, `[::1]`).
- **Bắt buộc xác thực HMAC (`requireHmac`)**: Khi bật, mọi lệnh gọi `identify()` phải đính kèm chữ ký HMAC tạo từ máy chủ của bạn bằng **`hmacSecret`**.
- **Xoay vòng Secret (Rotate Secret)**: Tạo `hmacSecret` mới và vô hiệu hóa ngay các phiên JWT khách truy cập cũ.
:::caution[Xóa Widget]
Xóa Widget (`nick:delete`) sẽ xóa kênh Website và toàn bộ hội thoại gắn với Widget đó. Nếu chỉ muốn tạm ngưng hiển thị chat, hãy chuyển trạng thái Widget sang **`PAUSED`**.
:::
## Giới hạn kỹ thuật của Public SDK
Để chống spam và đảm bảo ổn định, Public SDK áp dụng các giới hạn mặc định sau:
- **Tin nhắn khách truy cập**: Tối đa **2.000 ký tự** và tối đa **5 tệp đính kèm** mỗi tin nhắn.
- **Tải tệp đính kèm (ảnh / PDF)**: Tối đa **5 MB** mỗi tệp.
- **Giới hạn tần suất (Rate Limit)**:
- Khởi tạo phiên: **15 yêu cầu / 5 phút** mỗi IP.
- Gửi tin nhắn: **25 yêu cầu / phút** mỗi IP và **10 yêu cầu / phút** mỗi khách truy cập.
- Tải tệp: **10 yêu cầu / phút** mỗi IP và **3 yêu cầu / phút** mỗi khách truy cập.
## Tài liệu liên quan
- [Tổng quan kênh kết nối](/vi/channels/overview/)
Kênh Website (/{slug}/channels/website) cho phép bạn tạo một hoặc nhiều khung chat trực tuyến (Live Chat SDK) nhúng trực tiếp vào website, kết nối với Bot AI và quản lý hội thoại tập trung trong Workspace.
Tạo Website Widget mới
Phần tiêu đề “Tạo Website Widget mới”- Truy cập Kênh kết nối → Website (
/{slug}/channels/website) và nhấn Thêm kênh (mở trang/{slug}/channels/website/new). - Nhập tên kênh Website (tối đa 100 ký tự), cấu hình giao diện cơ bản và chọn Bot AI phụ trách.
- Nhấn lưu để tạo Widget. Hệ thống sẽ sinh
siteKeyvàhmacSecretriêng cho Widget và chuyển bạn tới trang quản lý chi tiết (/{slug}/channels/website/{widgetId}).
4 thẻ cấu hình trong không gian Widget
Phần tiêu đề “4 thẻ cấu hình trong không gian Widget”1. Widget (Giao diện & Nội dung)
Phần tiêu đề “1. Widget (Giao diện & Nội dung)”Tùy chỉnh trực quan kèm khung Xem trước tương tác (Live Preview) ngay bên cạnh:
- Màu sắc & Giao diện: Màu chủ đạo (mã hex), chế độ màu (
light,dark,system), phông chữ (System,Inter,Roboto,Be Vietnam Pro,Plus Jakarta Sans,Nunito,Montserrat,Open Sans), độ bo góc (sharp,rounded,pill) và kích thước cửa sổ (compact350×480,default390×560,large430×640). - Vị trí & Hiển thị: Góc dưới phải (
bottom-right) hoặc dưới trái (bottom-left), khoảng cách lề X/Y (0–200px), kích thước nút mở chat (36–96px) và thời gian tự động mở (1–300giây, tùy chọn). - Nội dung chào mừng: Tiêu đề khung chat (tối đa 80 ký tự), phụ đề trạng thái (tối đa 120 ký tự), ảnh đại diện (tối đa 2 MB), lời chào mở đầu (tối đa 500 ký tự), văn bản gợi ý ô nhập (tối đa 80 ký tự) và tối đa 4 câu hỏi gợi ý (Quick Replies) (mỗi câu tối đa 60 ký tự).
- Biểu mẫu trước khi chat (Pre-chat Form): Khi bật, khách truy cập cần nhập Họ tên và Số điện thoại (tùy chọn yêu cầu thêm Email) trước khi bắt đầu trò chuyện.
2. Hội thoại (Conversations)
Phần tiêu đề “2. Hội thoại (Conversations)”- Theo dõi và chuyển đổi trạng thái hoạt động của Widget giữa
CONNECTED(đang hoạt động) vàPAUSED(tạm dừng). - Chọn Bot AI phụ trách và bật/tắt chế độ AI tự động trả lời cho Widget.
3. Cài đặt (Install)
Phần tiêu đề “3. Cài đặt (Install)”Nhúng đoạn mã SDK trước thẻ đóng </body> trên website của bạn:
<script src="https://<domain-omnybot>/sdk/v1/widget.iife.js" data-site-key="<SITE_KEY>" async></script>Trang cài đặt cung cấp sẵn mẫu mã cho 7 nền tảng: HTML Snippet, React / Next.js, Angular, Vue, WordPress, Google Tag Manager (GTM) và Shopify, với hai chế độ:
- Khách ẩn danh (Anonymous): Chỉ cần nhúng thẻ
<script>cơ bản. - Khách đã đăng nhập (Logged-in): Gọi
window.OmnyBot("identify", { externalId, name, phone, email, hmac })để đồng bộ danh tính khách hàng từ hệ thống của bạn.
4. Bảo mật (Security)
Phần tiêu đề “4. Bảo mật (Security)”- Domain được phép nhúng (
allowedDomains): Nhập tối đa 20 tên miền (hỗ trợ wildcard như*.example.com). Nếu để trống, Widget chấp nhận mọi tên miềnhttp/https. - Cho phép
localhost: Bật khi cần thử nghiệm nhúng trên môi trường phát triển cục bộ (localhost,127.0.0.1,[::1]). - Bắt buộc xác thực HMAC (
requireHmac): Khi bật, mọi lệnh gọiidentify()phải đính kèm chữ ký HMAC tạo từ máy chủ của bạn bằnghmacSecret. - Xoay vòng Secret (Rotate Secret): Tạo
hmacSecretmới và vô hiệu hóa ngay các phiên JWT khách truy cập cũ.
Giới hạn kỹ thuật của Public SDK
Phần tiêu đề “Giới hạn kỹ thuật của Public SDK”Để chống spam và đảm bảo ổn định, Public SDK áp dụng các giới hạn mặc định sau:
- Tin nhắn khách truy cập: Tối đa 2.000 ký tự và tối đa 5 tệp đính kèm mỗi tin nhắn.
- Tải tệp đính kèm (ảnh / PDF): Tối đa 5 MB mỗi tệp.
- Giới hạn tần suất (Rate Limit):
- Khởi tạo phiên: 15 yêu cầu / 5 phút mỗi IP.
- Gửi tin nhắn: 25 yêu cầu / phút mỗi IP và 10 yêu cầu / phút mỗi khách truy cập.
- Tải tệp: 10 yêu cầu / phút mỗi IP và 3 yêu cầu / phút mỗi khách truy cập.