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

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

> Tạo kênh Website trên Console, dán mã nhúng vào website hoặc chia sẻ qua đường dẫn và mã QR

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

<Steps>
  <Step title="Mở Agent và vào tab Kênh triển khai">
    Đăng nhập [Console FPT AI](https://console-agents.fpt.ai/), chọn Agent bạn muốn cấu hình, rồi mở tab **Kênh triển khai**.
  </Step>

  <Step title="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](/tich-hop/live-chat-api/live-chat/tuy-bien-giao-dien). |
  </Step>

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

<Warning>
  **Đườ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.
</Warning>

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

```mermaid theme={null}
sequenceDiagram
  participant W as Widget (trình duyệt)
  participant V as Visitor API
  participant A as AI Agents
  W->>V: GET /v1/visitor/config?connectionKey=…
  V-->>W: Giao diện, lời chào, câu gợi ý
  W->>V: POST /v1/visitor/session
  V-->>W: visitorToken + sessionId
  W->>V: GET /v1/sessions/{sessionId}/stream (SSE)
  W->>V: POST /v1/runs (Bearer visitorToken)
  V->>A: Chạy Agent
  loop Phát token
    A-->>V: token…token…token
    V-->>W: Sự kiện AG-UI qua SSE
  end
  V-->>W: RunFinished
```

## Nhúng widget vào website

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.

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

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

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

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

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

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

```text theme={null}
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.

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


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