> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kênh Live Chat

> Đưa Agent lên website của bạn: cấu hình kênh trên Console, dán mã nhúng vào website, chia sẻ qua đường dẫn và mã QR, tùy biến giao diện khung 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 đó.

<Info icon="globe">
  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".
</Info>

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

<Steps>
  <Step title="Đăng nhập FPT AI Agent Platform">
    Mở Console và đăng nhập bằng tài khoản của bạn.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Mở tab Channels">
    Tab **Channels** nằm trên thanh điều hướng của Agent.
  </Step>

  <Step title="Chọn ô Web widget">
    Bảng "Web client configuration" mở ra bên phải.
  </Step>

  <Step title="Điền cấu hình trong hai thẻ">
    Thẻ **Config** và thẻ **Customize widget**. Chi tiết ở hai mục ngay dưới.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<Note>
  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ẻ.
</Note>

## Thẻ Config

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_config.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=0a4b63bc6e7b2042453664e3d12a6279" alt="Thẻ Config của Web widget" width="1568" height="706" data-path="images/lc_config.jpg" />

### 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.

<Note>
  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](/tich-hop-api).
</Note>

**Thêm domain**

<Steps>
  <Step title="Bấm + Add domain">
    Một dòng nhập mới xuất hiện trong danh sách.
  </Step>

  <Step title="Nhập tên miền">
    Ví dụ `https://shop.congty.vn`. Không thêm đường dẫn phía sau.
  </Step>

  <Step title="Bấm Save configuration">
    Thay đổi có hiệu lực ngay sau khi lưu.
  </Step>
</Steps>

**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.

## Nhúng widget vào website

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.

```html theme={null}
<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:

```text theme={null}
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ẻ Customize widget

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.

<Note>
  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.
</Note>

### Theme - Màu sắc

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_theme.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=64ba73a75b0a5d8506ab6de470fe4b61" alt="Tùy biến màu sắc widget" width="1568" height="706" data-path="images/lc_theme.jpg" />

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.

<Tip>
  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.
</Tip>

### General - Thông tin chung

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_general.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=75de43e6305328c97848ba3a6f228039" alt="Thiết lập chung của widget" width="1568" height="706" data-path="images/lc_general.jpg" />

| 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 |

<Warning>
  Đặ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.
</Warning>

<Note>
  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](/tich-hop-api).
</Note>

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

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_starter.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=8cde9ca698a0c1cb0079f4479a9648b6" alt="Câu hỏi gợi ý" width="1568" height="706" data-path="images/lc_starter.jpg" />

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ự.

<Steps>
  <Step title="Bấm + Add question">
    Một dòng nhập mới xuất hiện.
  </Step>

  <Step title="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".
  </Step>

  <Step title="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 đó.
  </Step>
</Steps>

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

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_welcome.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=a20664723758c0b7f8a4dc66ca68ab83" alt="Màn hình chào" width="1568" height="706" data-path="images/lc_welcome.jpg" />

| 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

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/lc_chat.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=9507c0468bff19f658e67cfb4a10808b" alt="Thiết lập khung trò chuyện" width="1568" height="706" data-path="images/lc_chat.jpg" />

| 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 |

<Warning>
  Đừ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.
</Warning>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Hủy thay đổi">
    Bấm **Cancel** để đóng bảng mà không lưu.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

* `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

<CardGroup cols={3}>
  <Card title="SDK di động" icon="mobile-screen" href="/sdk-di-dong">
    Đưa đúng khung chat này vào ứng dụng Android và iOS của bạn.
  </Card>

  <Card title="Tích hợp API" icon="code" href="/tich-hop-api">
    Dùng khi bạn đã có sẵn giao diện chat riêng với khách hàng.
  </Card>

  <Card title="Phụ lục kỹ thuật" icon="table-list" href="/phu-luc-ky-thuat">
    Bảng mã lỗi, bảng giới hạn hệ thống và danh mục kiểm tra trước Production.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.