Website

Có ba cách đưa AI Agent Quickchat lên web. Hãy chọn hình thức phù hợp với nơi bạn muốn hiển thị:

• Widget: bong bóng chat nổi ở góc website. Phù hợp nhất cho hỗ trợ đa dụng.
• Embed: cửa sổ chat trong trang, đặt đúng vị trí bạn muốn. Phù hợp để nhúng AI vào màn hình ứng dụng cụ thể, trang trung tâm trợ giúp hoặc trang chi tiết sản phẩm.
• Chat Page: trải nghiệm chat toàn màn hình do Quickchat lưu trữ, không cần cài đặt hay mã. Phù hợp khi muốn chia sẻ liên kết, chẳng hạn qua email hỗ trợ, Slack nội bộ hoặc cho người thử nghiệm beta, mà không cần can thiệp vào trình duyệt của họ.

Cài đặt hình thức đã chọn tại Channels → Your Website → Install. Trang có ba thẻ phụ: Install để chọn cách thêm AI Agent, Appearance để chỉnh giao diện và Text Content cho nội dung, nhãn mà khách nhìn thấy. Thẻ Install mở đầu bằng bộ chọn phương thức, tách khả năng sử dụng và quyền truy cập thành phần riêng, đồng thời hiển thị Scenario ID có thể sao chép cho plugin và API.

Công cụ thiết lập tùy chọn

• So sánh các phương thức triển khai. Đối chiếu các kênh, quyền truy cập website và tính năng cần thiết mà bạn cung cấp với các lựa chọn thiết lập Quickchat AI. Công cụ này không kiểm tra website hoặc tài khoản của bạn.

• So sánh HTML và Markdown của trang mẫu. Lấy nội dung HTML ban đầu, Markdown và liên kết công cụ từ một mẫu Quickchat AI cố định. Công cụ không chạy JavaScript hoặc kiểm tra website tùy ý.

Widget

Widget cho phép nhúng AI Agent Quickchat trực tiếp vào website, giúp người dùng tương tác với AI thuận tiện. Widget thường hiển thị dưới dạng bong bóng chat ở góc dưới bên phải. Khi nhấp, nó mở thành cửa sổ chat để người dùng đặt câu hỏi, nhận hỗ trợ hoặc tìm thông tin.

Cách thêm Widget vào website

Mở Channels → Your Website → Install. Thẻ bắt đầu bằng “How do you want to add your AI Agent?” và liệt kê các phương thức cài đặt từ dễ nhất. Chọn cách phù hợp với website:

• WordPress: cài plugin Quickchat AI Agent miễn phí, dán Scenario ID và Widget tự xuất hiện, không phải sửa mã giao diện.
• Shopify: thêm Widget qua Theme Editor của cửa hàng. Xem hướng dẫn Shopify.
• Webflow, Wix & others: sao chép một đoạn mã rồi dán vào cài đặt mã tùy chỉnh toàn website của trình dựng trang, áp dụng cho mọi trang. Không dùng phần tử Embed hoặc HTML trên một trang. Xem Trình dựng website.
• Share a link instead: không cần cài gì; chia sẻ liên kết Chat Page được lưu trữ sẵn.
• Install manually with code: sao chép đoạn mã Widget hoặc Embed nguyên bản rồi tự dán vào HTML.

Mỗi phương thức mở một bảng hướng dẫn tập trung, từng bước, chỉ gồm mã hoặc ID cần thiết.

Scenario ID nằm ở đầu thẻ Install trong trường có thể sao chép. Đây là định danh plugin và API cần, nên hãy sao chép tại đây khi bước thiết lập yêu cầu.

Cài đặt thủ công bằng mã

Nếu tự quản lý HTML, mở Install manually with code trên thẻ Install rồi:

1. Sao chép đoạn mã Widget.
2. Mở tệp HTML của trang. Nếu dùng trình dựng website, hãy dùng cài đặt mã toàn website thay thế; xem Trình dựng website.
3. Dán đoạn mã ngay trước thẻ đóng </body> trên mỗi trang muốn hiển thị Widget.

Kiểm tra đoạn mã Widget với Scenario ID bạn cung cấp. Công cụ đọc mã đã dán, không truy cập website.

Trình dựng website

Trên Webflow, Wix, Squarespace, Hostinger và các công cụ tương tự, chỉ thêm Widget một lần qua cài đặt mã toàn website:

1. Mở cài đặt thêm mã cho mọi trang. Công cụ thường gọi là Custom code, Code injection, Footer code hoặc Body end.
2. Dán mã Widget tại đó và áp dụng cho mọi trang. Nếu được chọn vị trí, chọn chân trang hoặc cuối body. Đoạn mã không hoạt động trong head.
3. Xuất bản website. Bong bóng chat xuất hiện trên mọi trang.

Chú ý

Không thêm Widget bằng phần tử Embed hoặc HTML đặt trên một trang. Nhiều trình dựng hiển thị các phần tử đó trong khung nhỏ riêng, và Widget không thể mở bên trong. Ngay cả khi tải được, nó cũng chỉ xuất hiện trên đúng trang đó.

Vị trí cài đặt toàn website:

Trình dựng	Cài đặt mã toàn website
Webflow	Site settings → Custom code → Footer code
Wix	Settings → Custom Code, rồi All pages và Body - end. Cần tên miền đã kết nối.
Squarespace	Custom Code → Code Injection → Footer. Có trên Core, Plus, Advanced và một số gói cũ.
Hostinger Website Builder	More (⋯) → Integrations → Custom code. Tập lệnh tự tải ở cuối trang.

Menu có thể thay đổi hoặc được dịch theo ngôn ngữ trình dựng website. Nếu công cụ hoặc gói của bạn không có cài đặt mã toàn website, hãy chia sẻ liên kết Chat Page.

Cần trợ giúp?

Không phải lập trình viên? Thẻ Install có hai lối tắt dưới Need a hand?:

• Ask AI for help: mở trợ lý trong ứng dụng, điền sẵn câu hỏi về cách thêm Agent vào website.
• Email instructions to a developer: gửi cho đồng đội mọi thứ cần thiết, gồm mã Widget, Scenario ID và liên kết hướng dẫn này, để họ cài giúp bạn.

Nếu cần hỗ trợ thêm, liên hệ contact@quickchat.ai.

Chat Page

Chat Page là phiên bản AI Agent toàn màn hình được lưu trữ trên URL Quickchat. Không cần cài đặt: chỉ chia sẻ liên kết để khách chat với Agent trực tiếp trong trình duyệt. Dùng khi:

• Bạn muốn có trải nghiệm chat nhưng không có website hoặc không muốn chạm vào mã.
• Bạn chia sẻ AI nội bộ với nhóm nhỏ như người thử beta, nhóm hỗ trợ hoặc khách hàng tiềm năng, và cần liên kết có kiểm soát truy cập thay vì widget công khai.
• Bạn muốn gửi AI như một kênh tiếp nối qua email, Slack hoặc CRM.

Cấu hình ai được mở Chat Page tại Install → Chat Page Access. Xem Kiểm soát truy cập bên dưới.

Bắt đầu cuộc trò chuyện mới

Để đặt lại chat và bắt đầu mới:

• Widget hoặc Embed: Mở chat rồi nhấp nút hình bút trong ô vuông ở góc trên bên phải cửa sổ.
• Chat Page: Chọn New chat trong thanh bên hoặc dùng nút hình bút trong ô vuông ở phần đầu.

Thao tác này tạo cuộc trò chuyện mới với AI Agent. Cuộc trò chuyện cũ vẫn nằm trong Inbox. Đóng rồi mở lại Widget hoặc tải lại trang có thể tiếp tục cuộc trò chuyện hiện có. Yêu cầu AI “đặt lại” hoặc “xóa chat” không tạo cuộc trò chuyện mới. Bạn không cần xóa cookie trình duyệt.

Kiểm soát truy cập

Thẻ Install đặt quyền truy cập trong phần có thể thu gọn Availability and access. Mở rộng để thấy hai điều khiển áp dụng cho triển khai:

Quyền truy cập Widget và Embed

Công tắc ở đầu Availability and access. Khi bật, tập lệnh Widget và Embed hoạt động bình thường trong trình duyệt khách. Khi tắt, Widget và Embed không khả dụng trên website dù mã vẫn còn được dán. Hữu ích để tạm ngừng AI mà không gỡ mã, hoặc hạn chế truy cập công khai trong khi vẫn mở Chat Page cho người được mời.

Chat Page Access

Độc lập với công tắc Widget và Embed, bạn có thể hạn chế người mở Chat Page:

• Anyone: URL Chat Page công khai. Ai có liên kết đều dùng được.
• Invited users only: chỉ Chat Users được bạn mời qua email dùng được Chat Page. Họ cần xác thực.
• Nobody: tắt hoàn toàn Chat Page.

Liên kết Invite Chat Users mở Settings → Organization → Team Members. Biểu mẫu mời hiện tại cung cấp vai trò nhóm có quyền bảng điều khiển; không có vai trò riêng chỉ chat hoặc phần Chat Users. Xem Thành viên nhóm và vai trò trước khi mời ai đó.

Tùy chỉnh

Các thẻ phụ Appearance và Text Content cho phép điều chỉnh diện mạo Widget, Embed, Chat Page và nội dung khách nhìn thấy. Cả ba hình thức dùng chung cài đặt: đổi một lần để áp dụng ở mọi nơi Agent triển khai.

Bảng bên phải của Install/Appearance/Text Content có điều khiển xem trước riêng. Chuyển giữa Widget, Embed, Chat Page và khung nhìn Desktop, Mobile để thấy thay đổi trước khi xuất bản.

Appearance

Giao diện chat được chia thành Branding, Size & Position, Theme và Other Settings.

Branding

• AI Agent Avatar: ảnh đại diện hoặc logo Agent, một ảnh dùng cả ở đầu chat và nút mở chat, tối đa 5 MB. Đây là một cài đặt, không phải hai: tải một ảnh và ảnh xuất hiện ở cả hai nơi, thay cho “header logo” và “launcher icon” riêng trước đây. Mỗi Agent bắt đầu với ảnh đại diện mặc định. Reset to default khôi phục ảnh này; xóa ảnh sẽ không hiển thị ảnh đại diện nào. Có trên mọi gói, kể cả Free.

AI Agent Avatar áp dụng cho Widget, Embed và Chat Page, nhưng không áp dụng Discord, nơi ảnh bot lấy từ ứng dụng Discord của bot. Xem Discord.

Size & Position

• Launcher size: Classic, Input Only hoặc Small. Điều chỉnh cách nút mở chat hiển thị trước khi mở.
• Đóng nút mở chat: kiểu Classic có nút đóng nhỏ ở góc trên bên phải, hiện khi di chuột trên máy tính và luôn hiện trên thiết bị cảm ứng. Nút chỉ ẩn widget trong lượt xem trang hiện tại; nút mở chat quay lại ở lần tải trang sau. Các kích thước khác không có nút đóng.
• Launcher label: chỉ hiện khi chọn Small. Văn bản tùy chỉnh trên nút nhỏ, tối đa 25 ký tự, ví dụ “Ask AI” hoặc “Chat”. Để trống để chỉ hiện biểu tượng.
• Widget position: dưới trái, dưới giữa hoặc dưới phải.
• Kích thước cửa sổ chat: rộng 300–700px và cao 400–1200px.
• Draggable launcher: cho phép khách kéo nút mở chat sang vị trí khác trên trang, hữu ích khi che nội dung quan trọng.

Theme

Chọn màu sắc cho giao diện chat:

• Light và Dark là bộ thiết lập cố định, hiển thị giống nhau trên mọi tài khoản.
• Custom mở bảng màu riêng đầy đủ. Khi chọn, các điều khiển màu xuất hiện cho nền, phần đầu và chữ phần đầu, màu nhấn dùng ở nút bắt đầu trước chat, gợi ý và thao tác đánh giá, bong bóng tin nhắn và chữ, chữ tin nhắn AI, màu liên kết, ô nhập, viền và nhiều phần khác. Mỗi màu được kiểm tra độ tương phản WCAG AA với nền, kèm cảnh báo nếu phối màu khó đọc.

Màu phần đầu và màu nhấn theo thương hiệu nằm trong Custom. Light và Dark giữ vai trò bộ màu trung tính, nên chuyển giữa chúng không mang theo màu tùy chỉnh.

Trong Transparency, cài đặt Background chọn độ xuyên thấu của cửa sổ chat. Tính năng dùng được với mọi chế độ giao diện, còn giao diện cung cấp màu phủ:

• Solid: cửa sổ chat có nền đặc. Đây là mặc định.
• Glass: cửa sổ trở nên trong suốt và làm mờ website phía sau như kính mờ. Màu phủ là trắng ở Light, tối ở Dark, và theo màu nền của bạn ở Custom. Trong Custom, màu phần đầu khác màu nền vẫn được giữ để thể hiện thương hiệu. Glass opacity đặt mức độ màu phủ che trang, từ mức thấp nhất giữ chữ dễ đọc trên mọi website, là 50% ở Light, 65% ở Dark, tùy màu ở Custom, đến 95%. Nếu không có độ mờ nào giúp chữ đọc được với màu Custom, widget dùng nền đặc và cài đặt giải thích lý do. Glass vẫn được chọn và sẽ áp dụng lại khi bạn chỉnh màu chữ hoặc nền để đủ tương phản.

Độ trong suốt áp dụng cho Widget, kể cả điện thoại, và Embed. Chat Page toàn trang luôn có nền đặc. Khách bật “Reduce transparency” trên thiết bị sẽ thấy kiểu Solid trong Chrome và Edge, hai trình duyệt truyền tùy chọn này cho website. Trong trình duyệt không thể làm mờ trang, Glass giữ gần như đặc để chữ vẫn đọc được.

Khi chọn Custom, Chat Page còn có màu thanh bên riêng: Sidebar background, Sidebar text, Sidebar hover và Sidebar hover text. Chúng chỉ áp dụng Chat Page toàn trang, không áp dụng bong bóng Widget hay Embed. Để màu chữ chưa đặt, Chat Page sẽ tự chọn màu dễ đọc với nền bạn chọn.

Bạn cũng có thể đặt bán kính góc, tức độ bo tròn bong bóng, ô nhập và nút, cùng cỡ chữ. Cả hai áp dụng cho mọi chế độ giao diện.

Other Settings

• Voice Input: cho khách ghi âm lời nói bằng micro trong ô chat. Âm thanh được chuyển thành văn bản trong ô nhập để họ chỉnh sửa trước khi gửi. Ghi âm tự dừng sau hai phút; có trên gói trả phí.
• File Attachments: cho khách đính kèm ảnh hoặc tài liệu vào tin nhắn. Bật mặc định; tắt để bỏ nút đính kèm khỏi ô chat.
• Auto-open Widget: tự mở Widget khi trang tải.
• Hide Quickchat AI Branding: ẩn dòng chân trang “Powered by Quickchat AI” để có trải nghiệm hoàn toàn mang thương hiệu riêng, trên gói có white-labeling.

Để khách đánh giá hội thoại, mở Conversations → Insights → Conversation Rating. Cài đặt và kết quả đều nằm trong thẻ đó; xem Đánh giá hội thoại.

Text Content

Mở Channels → Your Website → Text Content để sửa lời chào và văn bản khác khách nhìn thấy:

• Header text: văn bản ở đầu cửa sổ chat.
• Welcome message: tin nhắn đầu tiên của AI Agent khi bắt đầu mỗi hội thoại, ví dụ “Chào bạn, bạn cần hỗ trợ không?”.
• Show as a pop-up: công tắc hiển thị lời chào thành bong bóng nổi cạnh nút mở chat, đôi khi được gọi là “teaser” hoặc “launcher message”, nhằm thu hút chú ý trước khi khách nhấp. Bong bóng hiện chính nội dung Welcome message, nên sửa trường đó để đổi lời chào.
• Conversation starters: tối đa 3 tin nhắn mẫu hiện trước khi khách bắt đầu nhập. Nhấp một tin sẽ gửi nó làm tin nhắn đầu, hữu ích để hướng khách tới thế mạnh AI, như “Làm thế nào để cài widget?” hoặc “Bạn hỗ trợ tích hợp nào?”.
• Input placeholder: văn bản gợi ý trong ô nhập tin nhắn trống.
• Disclaimer text: văn bản hiển thị phía sau hội thoại, thường thông báo người dùng đang nói chuyện với AI. Chúng tôi khuyên giữ nội dung rõ và dễ thấy.

Phần Pre-chat Screen ở dưới các trường này trong cùng thẻ Text Content. Bật tại đó rồi sửa văn bản tiêu đề, nút và thông điệp.

Ngôn ngữ và bản dịch

Theo mặc định, Text Content hiển thị cho mọi khách đúng như bạn nhập. Với gói trả phí, bạn có thể thêm bản dịch theo ngôn ngữ để khách thấy widget bằng ngôn ngữ của mình.

1. Mở thẻ phụ Text Content và nhấp Translate trong Other languages. Bảng Translate widget text mở ra, đặt nội dung chính cạnh mỗi bản dịch dưới nhãn Default (source).
2. Nhấp Add language rồi chọn ngôn ngữ. Quickchat AI tạo bản dịch nội dung hiện tại. Xem lại và chỉnh các trường cho ngôn ngữ đó: phần đầu, lời chào, câu mở đầu, gợi ý ô nhập, màn hình trước chat và tuyên bố lưu ý. Thay đổi tự lưu.
3. Trường để trống dùng lại văn bản mặc định, nên bạn chỉ dịch phần muốn thay đổi. Nếu dịch tự động thất bại, bạn vẫn nhập nội dung thủ công được.

Số ngôn ngữ có thể thêm tùy thuộc gói.

Cách chọn ngôn ngữ của khách

Với Widget và Embed, Quickchat chọn ngôn ngữ theo thứ tự:

1. Giá trị ghi đè rõ ràng bạn đặt trong trình tải: _quickchat("language", "de"), gọi trước _quickchat("init", ...).
2. Thuộc tính <html lang> của trang: ví dụ <html lang="de"> cung cấp bản dịch tiếng Đức. Đây là cách được khuyến nghị: đặt lang đúng trên từng trang đã bản địa hóa và widget tự theo.
3. Ngôn ngữ trình duyệt của khách, rồi văn bản Default nếu không khớp.

Ghi chú

Nếu ngôn ngữ khách không có bản dịch, họ luôn thấy văn bản Default. Không có phần nào bị để trống.

Tính năng nâng cao: tham số tùy chỉnh

Widget và Embed Quickchat AI cho phép truyền tham số tùy chỉnh khi khởi tạo. Chúng có thể dùng để:

• bổ sung phân tích, vì có trong tệp CSV xuất từ nền tảng Quickchat
• cung cấp giá trị cho API Actions và cá nhân hóa câu trả lời khi được phép. AI nhận một tập con đã lọc, không phải mọi tham số; xem Ngữ cảnh mô hình và phân quyền

Ví dụ tham số hữu ích:

• visitor_name: Mike
• customer_tier: VIP
• order_id: ord_123

visitor_name là khóa liên hệ được nhận diện. Khóa tùy chỉnh như customer_tier có thể lưu và dùng trong Actions, nhưng chỉ gửi khóa không bảo đảm AI sẽ dùng trong câu trả lời. Xem giá trị từ trình duyệt là đầu vào chưa xác minh, không phải quyền truy cập tài khoản khách hàng.

Để thêm tham số như trên, đưa phần sau vào tập lệnh tìm thấy ở Your Website > Install.

Widget và Embed dùng cùng cấu trúc lời gọi:

_quickchat("custom_params", {
  "visitor_name": "Mike",
  "customer_tier": "VIP",
  "order_id": "ord_123",
});

Các thuộc tính được gắn cho mọi hội thoại mới; chúng tôi khuyên chỉ giữ một số ít khóa.

Mẹo

Tham số tùy chỉnh đặt tên snake_case, như order_id, customer_tier, có thể chèn trực tiếp vào API Actions dưới dạng {{metadata_order_id}}, {{metadata_customer_tier}}, v.v. Xem Biến AI Action để biết chi tiết.

Tập lệnh mẫu:

widget

<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>

Embed

<div id="quickchat-embedded" style="height:600px;overflow:hidden;"></div>
<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("containerId", "quickchat-embedded");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>

Embed

Embed cho phép đặt AI Agent Quickchat trực tiếp vào trang dưới dạng cửa sổ chat trong nội dung, thay vì bong bóng nổi. Dùng khi muốn chat nằm ở vị trí cụ thể, như cột trung tâm trợ giúp, trang liên hệ hoặc thanh bên trong ứng dụng.

Cách thêm Embed

1. Lấy mã Embed

   • Đăng nhập Quickchat AI App.
   • Vào Channels → Your Website ở thanh bên trái.
   • Nhấp thẻ Install rồi mở Install manually with code.
   • Sao chép đoạn mã Embed, gồm cả phần tử chứa <div id="quickchat-embedded"> và tập lệnh tải.

2. Mở tệp HTML website hoặc trang trong trình dựng website.

3. Dán mã

   • Chèn mã Embed vào <body> của trang.
   • Đặt đúng vị trí muốn cửa sổ chat xuất hiện. <div> kiểm soát kích thước; điều chỉnh style="height:600px" để khớp khoảng trống trong bố cục.
   • Trong trình dựng website, thêm phần tử mã hoặc HTML tại vị trí cửa sổ chat, rồi dán đoạn mã vào đó.

Ghi chú

Embed chỉ hoạt động khi trình dựng đặt mã trực tiếp vào trang. Một số công cụ, như Wix, hiển thị phần tử HTML trong khung riêng, và Embed không thể tải trong khung. Nếu cửa sổ chat không xuất hiện trên trang đã xuất bản, hãy thêm Widget qua cài đặt mã toàn website, hoặc chia sẻ liên kết Chat Page.