Kênh Live Chat

Live Chat là kênh Website: nền tảng 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. Khách hàng của bạn trò chuyện trực tiếp với Agent qua khung chat đó.

Bảng cấu hình mở từ tab Channels (Kênh triển khai) của Agent, bấm vào ô Web widget. Tiêu đề bảng là “Web client configuration”.

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

Đăng nhập FPT AI Agent Platform

Mở Console và đăng nhập bằng tài khoản của bạn.

Chọn Agent bạn muốn cấu hình

Agent này sẽ là Agent trả lời khách hàng trên website.

Mở tab Channels

Tab Channels nằm trên thanh điều hướng của Agent.

Chọn ô Web widget

Bảng “Web client configuration” mở ra bên phải.

Điền cấu hình trong hai thẻ

Thẻ Config và thẻ Customize widget. Chi tiết ở hai mục ngay dưới.

Bấm Save configuration

Kênh được tạo và bắt đầu phục vụ ngay. Ô Web widget chuyển sang Đã cấu hình.

Lần lưu đầu tiên chính là lúc kênh được tạo. Trước khi bấm lưu, kênh chưa tồn tại, nên đườ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.

Hai thẻ Config và Customize 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, đừng lưu riêng từng thẻ.

Thẻ Config

Whitelist domains

Danh sách tên miền website được phép dùng kênh này. Tối đa 20 mục, mỗi mục tối đa 253 ký tự. Mỗi mục là một tên miền, ví dụ https://shop.example.com, không kèm đường dẫn phía sau. Dùng * để cho phép mọi tên miền.

Nếu bạn chỉ dán đoạn mã nhúng theo hướng dẫn ở dưới thì để trống mục này. Chỉ cần khai tên miền khi bộ phận kỹ thuật của bạn tự dựng giao diện chat riêng, xem trang Tích hợp API.

Thêm domain

Bấm + Add domain

Một dòng nhập mới xuất hiện trong danh sách.

Nhập tên miền

Ví dụ https://shop.congty.vn. Không thêm đường dẫn phía sau.

Bấm Save configuration

Thay đổi có hiệu lực ngay sau khi lưu.

Sửa domain: Bấm vào domain trong danh sách, sửa lại rồi bấm Save configuration. Xóa domain: Bấm biểu tượng xóa ở cuối dòng, sau đó bấm Save configuration. Website dùng domain vừa xóa sẽ không gọi được lệnh tạo phiên nữa.

Đường dẫn chia sẻ, mã QR và mã nhúng

Ba giá trị này chỉ được tạo sau khi bạn lưu cấu hình lần đầu. Sau khi lưu, quay lại thẻ Config để sao chép. Sao chép đoạn mã trong thẻ Config và dán vào trước thẻ đóng </body> của mọi trang bạn muốn hiện khung chat.

<script
  src="https://console-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://console-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 nào khác, không cần CSS, và widget không kéo theo thư viện nào của bên thứ ba.

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ẻ Config cung cấp sẵn một đường dẫn mở thẳng khung chat toàn màn hình:

https://console-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. Thẻ này có năm tab con, kèm khung xem trước bên phải với ba trạng thái: Minimized, Welcome và Chat. Mọi thay đổi hiển thị ngay trong khung xem trước, và có hiệu lực ngay với các đoạn mã đã dán từ trước, vì widget đọc lại cấu hình mỗi lần khách hàng mở trang.

Trường nào bạn không đổi thì không được ghi xuống, nên khi nền tảng cập nhật bộ màu mặc định, kênh của bạn tự hưởng theo.

Theme - Màu sắc

Tất cả đều ở dạng #rrggbb. Giá trị sai định dạng bị từ chối khi lưu.

Trường	Mô tả	Mặc định
`theme.background`	Nền của khung chat	`#FFFFFF`
`theme.brand`	Màu thương hiệu: nền đầu khung chat và nền nút chat	`#203BDC`
`theme.brand_text`	Màu chữ và biểu tượng trên nền thương hiệu	`#FFFFFF`
`theme.customer_bubble`	Nền bong bóng tin nhắn của khách hàng	`#203BDC`
`theme.customer_text`	Màu chữ trong bong bóng của khách hàng	`#FFFFFF`
`theme.bot_bubble`	Nền bong bóng tin nhắn của Agent	`#F1F5F9`
`theme.bot_text`	Màu chữ trong bong bóng của Agent	`#020817`
`theme.primary`	Màu nhấn chung	`#203BDC`
`theme.header_style`	Kiểu tô màu đầu khung chat: `solid` hoặc `gradient`	`solid`

Bấm Reset default để đưa toàn bộ màu về mặc định.

Lấy đúng mã màu thương hiệu từ bộ nhận diện của công ty, và kiểm tra độ tương phản giữa chữ và nền để chữ vẫn đọc được.

General - Thông tin chung

Trường	Mô tả
`name`	Tên hiển thị trên đầu khung chat và trên trang chat
`avatar_url`	Ảnh đại diện. Tải lên dạng PNG hoặc JPEG, tối thiểu 256 x 256 px, tối đa 2 MB. Để trống thì hệ thống dùng chữ cái đầu tên Agent
`theme.position`	Góc đặt nút chat: `left` hoặc `right`
`locale_default`	Ngôn ngữ mặc định: `vi`, `en`, `ja`, `id`, `zh`
`launcher.greeting`	Lời chào hiện trong bong bóng cạnh nút chat khi khung chat đang đóng. Tối đa 200 ký tự; để trống thì không hiện bong bóng. Khác với `welcome.title`, vốn là tiêu đề bên trong màn hình chào
`turnstile_sitekey`	Khóa Cloudflare Turnstile để chặn bot khi tạo phiên. Để trống là tắt

Đặt turnstile_sitekey thành chuỗi rỗng thay vì để trống sẽ bật cổng chống bot mà không khách hàng nào qua được.

Kênh Website không còn tùy chọn cửa sổ nghỉ. Hội thoại trên widget dùng cố định 24 giờ - im lặng quá 24 giờ thì tin nhắn kế tiếp của khách mở một hội thoại mới. Cửa sổ nghỉ vẫn cấu hình được cho kênh API, xem Tích hợp API.

Starter - Câu hỏi gợi ý

Câu hỏi gợi ý hiển thị thành các nút bấm trước khi khách gửi tin nhắn đầu tiên. Tối đa 6 câu, mỗi câu tối đa 120 ký tự.

Bấm + Add question

Một dòng nhập mới xuất hiện.

Nhập câu hỏi

Viết đúng cách khách hay hỏi, ví dụ “Kiểm tra đơn hàng của tôi”.

Sửa hoặc xóa

Bấm vào câu hỏi để sửa, bấm biểu tượng xóa ở cuối dòng để bỏ câu hỏi đó.

Khi chưa có câu nào, mục này hiển thị “No suggested questions yet”.

Welcome - Màn hình chào

Trường	Kiểu	Mô tả
`welcome.title`	chuỗi	Tiêu đề màn hình chào
`welcome.subtitle`	chuỗi	Mô tả ngắn dưới tiêu đề
`welcome.button_text`	chuỗi	Nhãn nút bắt đầu trò chuyện
`welcome.placeholder`	chuỗi	Gợi ý trong ô nhập tên của khách hàng
`welcome.hide_greeting`	đúng/sai	Bật để bỏ qua màn hình chào, vào thẳng khung chat
`welcome.guest_mode`	đúng/sai	Mặc định bật. Tắt để yêu cầu khách nhập tên trước khi trò chuyện; tên đó được lưu và Agent sẽ chào đúng tên

Bấm Reset default để trả các ô văn bản về nội dung gợi ý ban đầu.

Chat - Khung trò chuyện

Trường	Kiểu	Mô tả
`chat.placeholder`	chuỗi	Gợi ý trong ô soạn tin. Để trống thì widget dùng câu đã dịch sẵn của nền tảng
`chat.disclaimer`	chuỗi	Dòng khuyến cáo về nội dung do AI tạo, đặt cạnh ô soạn tin
`chat.powered_by`	chuỗi	Dòng chân khung chat. Mặc định “Powered by FPT.AI”; đặt rỗng để ẩn hẳn
`chat.show_logo_header`	đúng/sai	Hiện ảnh đại diện trên đầu khung chat. Mặc định bật
`chat.show_citations`	đúng/sai	Hiện thẻ nguồn trích dẫn dưới câu trả lời. Mặc định bật
`chat.allow_attachments`	đúng/sai	Cho phép khách hàng gửi tệp đính kèm. Mặc định bật

Đừng bỏ dòng khuyến cáo về AI. Đây là thông tin giúp người dùng biết họ đang nói chuyện với Agent chứ không phải nhân viên, và giúp bạn tuân thủ quy định về minh bạch AI.

Sửa và xóa cấu hình

Sửa cấu hình

Mở lại ô Web widget từ tab Channels, sửa những mục cần đổi rồi bấm Save configuration. Thay đổi có hiệu lực ngay ở mọi nơi đã nhúng mã, không cần nhúng lại.

Hủy thay đổi

Bấm Cancel để đóng bảng mà không lưu.

Ngừng phục vụ tạm thời

Mở hộp thoại Publish ở tab Dựng Agent, bỏ tích Web widget rồi xuất bản. Cấu hình widget vẫn được giữ lại.

Xóa kênh

Xóa cấu hình kênh gỡ kênh khỏi Console và ngừng phục vụ ngay lập tức.

Xóa kênh làm 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. Toàn bộ khách hàng và hội thoại đã phát sinh vẫn được giữ lại, không bị xóa. 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 khóa kết nối mới và bạn phải dán lại đoạn mã nhúng.

Access-Control-Allow-Credentials không bao giờ được đặt. Xác thực bằng Authorization: Bearer, không bằng cookie; đừng gọi với credentials: "include".
Retry-After nằm trong Access-Control-Expose-Headers; thiếu khai báo này thì trình duyệt không cho đọc nó, trong khi đó lại là header bạn cần khi gặp 429.

Header được chấp nhận: authorization, content-type, x-request-id, traceparent. Phương thức: GET, POST, OPTIONS.

Bước tiếp theo

SDK di động

Đưa đúng khung chat này vào ứng dụng Android và iOS của bạn.

Tích hợp API

Dùng khi bạn đã có sẵn giao diện chat riêng với khách hàng.

Phụ lục kỹ thuật

Bảng mã lỗi, bảng giới hạn hệ thống và danh mục kiểm tra trước Production.

Giới thiệu

Workspace FPT AI

Console FPT AI

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