Cấu hình và nhúng widget

Live Chat là kênh Website: chúng tôi cung cấp sẵn giao diện chat, bạn chỉ cần cấu hình trên Console rồi dán một đoạn mã vào trang của mình.

Cấu hình kênh Website trên Console

Mở Agent và vào tab Kênh triển khai

Đăng nhập Console FPT AI, chọn Agent bạn muốn cấu hình, rồi mở tab Kênh triển khai.

Chọn ô Web widget

Bảng điều khiển cấu hình gồm hai thẻ:

Thẻ	Nội dung cấu hình
Cấu hình	Danh sách tên miền được phép nhúng, đường dẫn chia sẻ kèm mã QR, và đoạn mã nhúng.
Tùy chỉnh widget	Màu sắc, tên hiển thị, ảnh đại diện, vị trí nút chat, ngôn ngữ mặc định, thời gian chờ, câu hỏi gợi ý, màn hình chào và tùy chọn khung chat. Gồm năm tab con: Màu sắc, Chung, Câu gợi ý, Lời chào và Khung chat. Xem chi tiết tại Tùy biến giao diện.

Bấm Lưu cấu hình

Lần lưu đầu tiên chính là lúc kênh được tạo. Kênh ở trạng thái đã kết nối và phục vụ khách hàng ngay; ô Web widget chuyển sang Đã cấu hình.

Đường dẫn chia sẻ, mã QR và đoạn mã nhúng chỉ xuất hiện sau lần lưu đầu tiên, vì trước đó kênh chưa tồn tại.Hai thẻ Cấu hình và Tùy chỉnh widget dùng chung một bản nháp và một nút lưu: một lần lưu ghi đè toàn bộ cấu hình của kênh. Hãy hoàn tất cả hai thẻ rồi mới bấm lưu.

Luồng một lượt trò chuyện

Sau khi lưu cấu hình, thẻ Cấu hình hiển thị sẵn đoạn mã nhúng. Sao chép và dán nó vào trước thẻ đóng </body> của mọi trang bạn muốn hiện khung chat.

<script
  src="https://agents.fpt.ai/chat-widget/chat-widget.iife.js"
  data-connection-key="wgt_abc123"
  data-workspace-id="1"
  data-agent-id="5"
  data-base-url="https://agents.fpt.ai/direct-bff"
  data-locale="vi"
  data-brand-color="#0B57D0"
  data-brand-text="#FFFFFF"></script>

Đoạn mã tự tạo nút chat ở góc màn hình. Bạn không cần thêm thẻ HTML hay CSS nào khác, và widget không kéo theo thư viện nào của bên thứ ba.

Thuộc tính của thẻ nhúng

Thuộc tính	Giá trị mẫu	Mô tả	Bắt buộc
`data-connection-key`	`wgt_abc123`	Khóa định tuyến của kênh, do nền tảng sinh. Thiếu thuộc tính này widget không hiện và không báo lỗi.	Bắt buộc
`data-base-url`	`https://agents.fpt.ai/direct-bff`	Địa chỉ Visitor API. Mặc định là thư mục chứa tệp script.	Tùy chọn
`data-app-origin`	`https://agents.fpt.ai/chat-widget/`	Nơi đặt ứng dụng chat. Mặc định là thư mục của tệp script, bình thường không cần khai báo.	Tùy chọn
`data-workspace-id`	`1`	Chỉ dùng để đối chiếu khi cần hỗ trợ, không ảnh hưởng định tuyến.	Tùy chọn
`data-agent-id`	`5`	Chỉ dùng để đối chiếu khi cần hỗ trợ, không ảnh hưởng định tuyến.	Tùy chọn
`data-locale`	`vi`	Ngôn ngữ ban đầu. Xem lưu ý bên dưới.	Tùy chọn
`data-title`	`Chat`	Tên gọi của khung chat dành cho trình đọc màn hình.	Tùy chọn
`data-brand-color`	`#0B57D0`	Màu nền nút chat, dạng `#rrggbb`. Giá trị sai định dạng bị bỏ qua.	Tùy chọn
`data-brand-text`	`#FFFFFF`	Màu biểu tượng trên nút chat, dạng `#rrggbb`.	Tùy chọn
`data-position`	`right`	Góc đặt nút chat: `left` hoặc `right`. Mặc định `right`.	Tùy chọn
`data-draggable`	`off`	`off` để khách hàng không kéo được nút chat. Mặc định cho phép kéo.	Tùy chọn
`data-z-index`	`2147483000`	Thứ tự xếp lớp của widget, dùng khi nút chat bị che.	Tùy chọn
`data-auto-open`	`true`	Tự mở khung chat ngay khi tải trang.	Tùy chọn
`data-preload`	`true`	Tải sẵn khung chat lúc vào trang thay vì đợi lần mở đầu tiên.	Tùy chọn
`data-sandbox`	`off`	`off` để bỏ thuộc tính sandbox của iframe. Chỉ dùng khi được hướng dẫn.	Tùy chọn
`data-auto`	`off`	`off` để giữ thẻ script nhưng không tự khởi tạo widget; bạn sẽ tự gọi `mountChatWidget()`.	Tùy chọn

Ngôn ngữ: data-locale trong đoạn mã đã dán là bản sao tĩnh tại thời điểm sao chép. Khi bạn đổi Ngôn ngữ mặc định trên Console, widget đang chạy tự đọc giá trị mới và ghi đè giá trị trong đoạn mã, nên bạn không phải dán lại. Đây là thuộc tính duy nhất hoạt động theo cách này.

Tên miền: data-app-origin phải giữ nguyên cả phần đường dẫn /chat-widget/. Nếu chỉ đưa tên miền gốc, trình duyệt sẽ tải ứng dụng khác đặt ở thư mục gốc: khung chat hiện ra trắng trơn và không có lỗi nào được ghi lại.

Đoạn mã nhúng đồng thời đăng ký một đối tượng toàn cục. Dùng nó khi bạn muốn mở khung chat từ một nút bấm có sẵn trên trang:

const chat = window.getChatWidget();

chat.open();              // mở khung chat
chat.close();             // đóng
chat.toggle();            // đảo trạng thái
chat.setFullscreen(true); // bật chế độ toàn màn hình
chat.isOpen();            // true | false
chat.on("chat-started", () => console.log("khách đã bắt đầu chat"));
chat.destroy();           // gỡ widget khỏi trang

Nếu bạn tự đặt vị trí widget bằng mountChatWidget(el, options), phần tử el phải là con trực tiếp của <body>. Đặt trong một phần tử cha có thuộc tính transform, filter, perspective hoặc contain sẽ làm nút chat neo sai vị trí.

Chia sẻ qua đường dẫn và mã QR

Khi bạn không muốn nhúng vào website, ví dụ gửi đường dẫn qua email, in mã QR lên tờ rơi hay đặt trên quầy, thẻ Cấu hình cung cấp sẵn một đường dẫn mở thẳng khung chat toàn màn hình:

https://agents.fpt.ai/chat-widget/?connectionKey=wgt_abc123&locale=vi

Mã QR bên cạnh mã hóa đúng đường dẫn này. Trang chat tự nhận diện thiết bị nên dùng được cả trên máy tính lẫn điện thoại.

Xóa kênh

Xóa cấu hình kênh sẽ gỡ kênh khỏi Console và ngừng phục vụ ngay: widget trên trang của bạn chuyển sang màn hình báo kênh không còn khả dụng. Khách hàng và hội thoại đã phát sinh vẫn được giữ lại.

Khóa kết nối cũ không dùng lại được. Tạo kênh Website mới sẽ sinh một connectionKey mới và bạn phải dán lại đoạn mã nhúng.

Giới thiệu

Workspace FPT AI

Console FPT AI

Cấu hình và nhúng widget

Cấu hình kênh Website trên Console

Luồng một lượt trò chuyện

Nhúng widget vào website

Thuộc tính của thẻ nhúng

Điều khiển widget bằng JavaScript

Chia sẻ qua đường dẫn và mã QR

Xóa kênh

​Cấu hình kênh Website trên Console

​Luồng một lượt trò chuyện

​Nhúng widget vào website

​Thuộc tính của thẻ nhúng

​Điều khiển widget bằng JavaScript

​Chia sẻ qua đường dẫn và mã QR

​Xóa kênh

Cấu hình kênh Website trên Console

Luồng một lượt trò chuyện

Nhúng widget vào website

Thuộc tính của thẻ nhúng

Điều khiển widget bằng JavaScript

Chia sẻ qua đường dẫn và mã QR

Xóa kênh