Widget chat là cách nhanh nhất để đặt trợ lý AI trước mặt khách truy cập: không cần xây app, không cần đăng nhập, và trợ lý trả lời từ cùng kho kiến thức bạn dùng ở mọi nơi khác. Phần cài đặt là một thẻ script. Những quyết định quanh nó mới là thứ phân biệt một widget giải quyết được ticket hỗ trợ với một widget làm bạn mất mặt ngay trên trang bảng giá.
Bài này đi qua phần cài đặt, những thiết lập đáng quyết định trước khi chạy thật, và JavaScript API nhỏ cho phép trang của bạn điều khiển widget.
Cài đặt
Trong trang quản trị, mở trợ lý, vào Kênh → Web Widget, thêm origin của website và sao chép đoạn mã. Nó đã chứa sẵn ID trợ lý của bạn:
<script
src="https://cdn.assistantcore.com/embed/embed.js"
data-assistant-id="YOUR_ASSISTANT_ID"
data-api-base="https://api.assistantcore.com"
async
></script>
Đặt nó một lần gần cuối <body>, hoặc trong root layout của framework để điều hướng phía client không tải lại lần hai. Với Next.js, đó là <Script strategy="lazyOnload"> trong root layout. Widget render trong Shadow DOM, nên CSS của site và CSS của widget không ảnh hưởng nhau, và nó chuyển sang bố cục toàn màn hình trên điện thoại.
Ba điều hay vấp ngay ngày đầu:
- Origin phải chính xác và là HTTPS.
https://example.comvàhttps://www.example.comlà hai origin khác nhau; thêm riêng production, staging và preview.http://localhostkhông được chấp nhận; hãy thử trên một URL preview HTTPS. - Một origin, một trợ lý. Dịch vụ chọn trợ lý từ origin của trang, nên một origin chỉ được phép trên một trợ lý.
- Content Security Policy. Nếu site đặt CSP, hãy cho phép
https://cdn.assistantcore.comtrongscript-srcvàhttps://api.assistantcore.comtrongconnect-src.
Widget cần tính năng Widget Embed trong gói của chủ trợ lý (từ Pro trở lên).
Quyết định widget được làm gì
Ai mở được site của bạn đều chat được, và mỗi câu trả lời trừ vào credit của chủ trợ lý. Trước khi công bố, hãy quyết định bốn điều:
Nó trả lời gì. Prompt nên nói rõ trợ lý dùng để làm gì, không được hứa gì, và hướng lại câu hỏi lạc đề ra sao. Đi kèm là một kho kiến thức phản ánh câu hỏi thật: giá, giao hàng, đổi trả, giờ mở cửa, và những câu đội của bạn vẫn trả lời bằng tay.
Nó được dùng công cụ nào. Mỗi công cụ có thể giới hạn ở từng kênh. Tắt những công cụ làm thay đổi dữ liệu, như tạo đơn, trên widget, và giữ những công cụ chỉ đọc. Công cụ xóa không bao giờ được cung cấp trên widget, vì không có người đăng nhập để phê duyệt.
Khách có được tải file lên không. Đính kèm của khách mặc định tắt. Khi bật, khách có thể gửi ảnh, PDF, tài liệu Office và file văn bản, tối đa năm file mỗi tin nhắn, có giới hạn theo giờ cho từng khách và từng mạng, và file bị xóa sau 30 ngày. Không nhận âm thanh và video.
Nó trông thế nào và nói gì. Giao diện sáng, tối hoặc theo thiết bị; góc dưới trái hoặc dưới phải; bong bóng chào hiện một lần mỗi lượt truy cập sau vài giây (không bao giờ trên điện thoại); tối đa bốn câu gợi ý mở đầu; chữ gợi ý trong ô nhập; và liên kết chính sách bảo mật ở chân widget. Tên, ảnh đại diện và màu thương hiệu lấy từ cài đặt của trợ lý.
Điều khiển widget từ trang của bạn
Sau khi tải, widget cung cấp một API nhỏ ở window.AssistantEmbed. Mẫu mà hầu hết site muốn là một nút "Chat với chúng tôi" theo thiết kế riêng và không có nút nổi mặc định:
<script
src="https://cdn.assistantcore.com/embed/embed.js"
data-assistant-id="YOUR_ASSISTANT_ID"
data-api-base="https://api.assistantcore.com"
data-hide-launcher
async
></script>
<button onclick="AssistantEmbed.open()">Chat với chúng tôi</button>
Điền sẵn tin nhắn từ trang khách đang xem biến một cuộc chat chung chung thành cuộc chat có ngữ cảnh:
AssistantEmbed.open({ message: "Tôi có câu hỏi về đơn #123" })
Khách vẫn tự nhấn gửi. Cho analytics, hãy lắng nghe sự kiện:
AssistantEmbed.on("open", () => track("chat_opened"))
AssistantEmbed.on("message", ({ text }) => track("chat_message"))
AssistantEmbed.on("reply", ({ text }) => track("chat_reply"))
Nếu mã của bạn chạy trước khi widget tải xong cấu hình, hãy xếp hàng các lệnh gọi; chúng chạy theo thứ tự khi widget phát assistantembed:ready:
<script>
window.AssistantEmbed = window.AssistantEmbed || []
AssistantEmbed.push(["open", { message: "Xin chào!" }])
</script>
Thuộc tính khác: data-lang ép en hoặc vi (nếu không, dùng <html lang> của trang, rồi ngôn ngữ trình duyệt, rồi tiếng Anh), và data-offset-x / data-offset-y dời nút nổi để tránh banner cookie hay nút nổi khác. AssistantEmbed.hideLauncher() hữu ích ở trang thanh toán.
Khách nhận được gì
Câu trả lời stream về với Markdown được render, và câu trả lời từ kho kiến thức có trích dẫn nguồn ngay dưới. Cuộc trò chuyện gần nhất được khôi phục khi khách quay lại trên cùng trình duyệt. Khách có thể đánh giá câu trả lời hữu ích hay không và nói rõ điều gì chưa ổn; đánh giá này góp vào chỉ số phản hồi tích cực trên dashboard. Khi một công cụ trả về thẻ kết quả, widget vẽ đầy đủ thẻ với ảnh và nút.
Mọi cuộc trò chuyện qua widget xuất hiện trong trang quản trị dưới kênh Widget, nên đội của bạn đọc được khách hỏi gì và sửa kho kiến thức ở chỗ câu trả lời còn yếu.
Quyền riêng tư
Widget lưu một ID khách ngẫu nhiên, cuộc trò chuyện gần nhất và trạng thái đã hiện lời chào trong trình duyệt của khách, và gửi tin nhắn cùng đính kèm tới trợ lý của bạn. Hãy nêu điều đó trong thông báo bảo mật, thêm địa chỉ thông báo làm liên kết bảo mật của widget, và kiểm tra yêu cầu về sự đồng ý ở các thị trường bạn phục vụ. Tại Việt Nam, Luật Bảo vệ dữ liệu cá nhân (Luật 91/2025/QH15) có hiệu lực từ 01/01/2026: dữ liệu khách để lại qua widget là dữ liệu doanh nghiệp bạn thu thập, nên thông báo bảo mật cần nói rõ bạn dùng nó vào việc gì.
Sau website
Cùng trợ lý trả lời trên site có thể trả lời trên Zalo OA, Messenger, WhatsApp và Telegram, và Developer API cho bạn cùng cơ chế chat streaming trong giao diện riêng khi widget chưa đủ. Tham chiếu đầy đủ cho mọi thiết lập nằm trong tài liệu Web Widget.