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

# Triển khai (Deploy)

> Triển khai AI agent ra các kênh tiếp cận khách hàng — từ chat widget trên website đến Zalo, Messenger, WhatsApp và nhiều nền tảng khác.

Trang Deploy là nơi bạn đưa AI agent ra tiếp cận khách hàng qua nhiều kênh khác nhau. Mỗi kênh có thể cấu hình độc lập với nội dung, giao diện và hành vi riêng.

## Tổng quan các kênh triển khai

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-overview.png" alt="Tổng quan trang Deploy" />
</Frame>

### Kênh chính

<CardGroup cols={2}>
  <Card title="Chat Widget" icon="message">
    Cửa sổ chat nổi nhúng trực tiếp vào website. Kênh phổ biến nhất, tương thích mọi thiết bị.
  </Card>

  <Card title="Trang trợ giúp" icon="circle-question">
    Trang hỗ trợ độc lập kiểu ChatGPT, có thể truy cập qua link riêng hoặc tích hợp vào website.
  </Card>
</CardGroup>

### Kênh khác

| Kênh                   | Mô tả                                   | Trạng thái |
| ---------------------- | --------------------------------------- | ---------- |
| **Zalo OA**            | Kết nối với Zalo Official Account       | Khả dụng   |
| **Facebook Messenger** | Phản hồi tin nhắn Facebook Messenger    | Khả dụng   |
| **Instagram**          | Trả lời tin nhắn và bình luận           | Khả dụng   |
| **Email**              | Tự động phản hồi email                  | Khả dụng   |
| **Điện thoại**         | Xử lý cuộc gọi đến bằng AI (qua Twilio) | Beta       |
| **Shopify**            | Hỗ trợ khách hàng trên cửa hàng Shopify | Khả dụng   |

<Info>
  Một số kênh yêu cầu gói dịch vụ cao hơn. Nhấn **"Nâng cấp để dùng"** trên
  card kênh để xem chi tiết gói cần thiết.
</Info>

***

## Triển khai Chat Widget

Chat Widget là một bong bóng chat nổi xuất hiện trên website. Khách hàng nhấn vào để bắt đầu trò chuyện với agent.

### Bật và quản lý widget

<Steps>
  <Step title="Bật widget">
    Trên card Chat Widget, bật switch **Hoạt động** để kích hoạt. Agent bị tắt chỉ dùng được nội bộ trong workspace.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-widget-toggle.png" alt="Bật/tắt Chat Widget" />
    </Frame>
  </Step>

  <Step title="Mở cài đặt">
    Nhấn **"Quản lý"** để vào trang cấu hình chi tiết.
  </Step>
</Steps>

### Nội dung (Content)

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-widget-content.png" alt="Tùy chỉnh nội dung widget" />
</Frame>

| Tùy chọn                   | Mô tả                                                                        |
| -------------------------- | ---------------------------------------------------------------------------- |
| **Tên hiển thị**           | Tên agent xuất hiện trên tiêu đề cửa sổ chat                                 |
| **Tin nhắn chào đầu tiên** | Tin nhắn tự động gửi khi khách hàng mở chat                                  |
| **Câu hỏi gợi ý**          | Các nút câu hỏi gợi ý khách hàng có thể nhấn. Hỗ trợ phân nhóm theo danh mục |
| **Thu thập phản hồi**      | Cho phép khách hàng đánh giá thumbs up/down sau mỗi câu trả lời              |
| **Sao chép tin nhắn**      | Hiển thị nút copy trên mỗi tin nhắn                                          |
| **Voice-to-text**          | Cho phép khách hàng nói thay vì gõ                                           |
| **Đính kèm file**          | Cho phép khách hàng gửi hình ảnh và PDF                                      |

<Info>
  Liên kết trong **chân trang (footer)** phải dùng URL đầy đủ (ví dụ:
  `https://example.com`) thay vì đường dẫn tương đối.
</Info>

### Hỗ trợ đính kèm file

Khi bật tính năng đính kèm, khách hàng có thể gửi hình ảnh và PDF để agent phân tích.

**Định dạng hỗ trợ:** PNG, JPG, JPEG và PDF.

**Giới hạn mỗi tin nhắn:**

* Tối đa **5 file**
* Tối đa **5 MB** mỗi file
* PDF tối đa **5 trang**
* Tối đa **2,000 token** mỗi trang

<Info>
  Credits được tính riêng cho phân tích file đính kèm (ngoài credits trả lời
  văn bản thông thường) — tính theo từng hình ảnh hoặc trang PDF.
</Info>

### Ngôn ngữ (Localization)

Widget có thể tự động hiển thị theo ngôn ngữ của trình duyệt khách truy cập.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-widget-localization.png" alt="Cài đặt ngôn ngữ" />
</Frame>

* Hỗ trợ nhiều ngôn ngữ, kể cả các ngôn ngữ viết từ phải sang trái.
* Chọn **ngôn ngữ mặc định** dùng cho các trình duyệt không được hỗ trợ.
* Bật **Tự động phát hiện ngôn ngữ** để widget tự điều chỉnh theo người dùng.

### Giao diện (Appearance)

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-widget-appearance.png" alt="Tùy chỉnh giao diện widget" />
</Frame>

| Tùy chọn                | Mô tả                                |
| ----------------------- | ------------------------------------ |
| **Giao diện (Theme)**   | Sáng hoặc Tối                        |
| **Màu chính**           | Màu nổi bật cho bong bóng và nút gửi |
| **Ảnh đại diện agent**  | Ảnh hiển thị bên cạnh tin nhắn AI    |
| **Icon bong bóng chat** | Icon trên nút chat nổi               |
| **Vị trí bong bóng**    | Góc phải hoặc góc trái màn hình      |

### Cài đặt AI theo kênh

Agent có thể dùng hướng dẫn (system prompt) riêng cho chat widget, khác với hướng dẫn chung.

* **Đồng bộ với hướng dẫn gốc:** Dùng system prompt chính.
* **Hướng dẫn riêng cho widget:** Thêm hoặc ghi đè hướng dẫn chỉ áp dụng khi khách hàng dùng chat widget.

### Giới hạn domain

Thêm danh sách domain được phép tải widget để tránh widget bị nhúng trên website không mong muốn.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-widget-domains.png" alt="Giới hạn domain" />
</Frame>

### Mã nhúng (Embed)

Nhấn tab **Nhúng** để lấy mã tích hợp vào website.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-embed-tab.png" alt="Tab nhúng mã widget" />
</Frame>

<Tabs>
  <Tab title="Chat Widget (Khuyến nghị)">
    **Phù hợp với đa số website**

    Bong bóng chat nổi — khách hàng nhấn để mở. Không ảnh hưởng đến thiết kế website. Hoạt động tốt trên di động.

    **Tốt nhất cho:** Website doanh nghiệp, blog, thương mại điện tử.
  </Tab>

  <Tab title="iFrame">
    **Dành cho phần chat cố định**

    Nhúng cửa sổ chat đầy đủ thẳng vào trang. Luôn hiện diện, phù hợp cho các trang hỗ trợ chuyên dụng.

    **Tốt nhất cho:** Trang trung tâm hỗ trợ, trang FAQ tương tác.

    <Info>
      iFrame có tính năng hạn chế hơn Chat Widget (không hỗ trợ một số tùy chỉnh nâng cao).
    </Info>
  </Tab>
</Tabs>

### Mã nhúng theo framework

<Tabs>
  <Tab title="HTML">
    Dán đoạn mã sau vào website, ngay trước thẻ `</body>`:

    ```html theme={null}
    <script>
    (function(){if(!window.agentbase||window.agentbase("getState")!=="initialized"){window.agentbase=(...args)=>{if(!window.agentbase.q){window.agentbase.q=[]}window.agentbase.q.push(args)};window.agentbase=new Proxy(window.agentbase,{get(t,p){if(p==="q")return t.q;return(...a)=>t(p,...a)}})}const onLoad=function(){const s=document.createElement("script");s.src="https://agentbase.vn/embed.min.js";s.id="YOUR_AGENT_ID";s.domain="agentbase.vn";document.body.appendChild(s)};if(document.readyState==="complete"){onLoad()}else{window.addEventListener("load",onLoad)}})();
    </script>
    ```

    <Tip>
      Đặt mã ngay trước `</body>` để website load trước, sau đó widget xuất hiện — giúp trang tải nhanh hơn.
    </Tip>
  </Tab>

  <Tab title="Next.js">
    Thêm vào `app/layout.tsx` (App Router):

    ```tsx theme={null}
    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html>
          <body>
            {children}
            <script dangerouslySetInnerHTML={{ __html: `(function(){if(!window.agentbase||window.agentbase("getState")!=="initialized"){window.agentbase=(...args)=>{if(!window.agentbase.q){window.agentbase.q=[]}window.agentbase.q.push(args)};window.agentbase=new Proxy(window.agentbase,{get(t,p){if(p==="q")return t.q;return(...a)=>t(p,...a)}})}const onLoad=function(){const s=document.createElement("script");s.src="https://agentbase.vn/embed.min.js";s.id="YOUR_AGENT_ID";s.domain="agentbase.vn";document.body.appendChild(s)};if(document.readyState==="complete"){onLoad()}else{window.addEventListener("load",onLoad)}})();` }} />
          </body>
        </html>
      );
    }
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={null}
    import { useEffect } from 'react';

    export function AgentbaseWidget() {
      useEffect(() => {
        if (document.getElementById('agentbase-widget')) return;
        const s = document.createElement('script');
        s.id = 'agentbase-widget';
        s.innerHTML = `(function(){if(!window.agentbase||window.agentbase("getState")!=="initialized"){window.agentbase=(...args)=>{if(!window.agentbase.q){window.agentbase.q=[]}window.agentbase.q.push(args)};window.agentbase=new Proxy(window.agentbase,{get(t,p){if(p==="q")return t.q;return(...a)=>t(p,...a)}})}const onLoad=function(){const s=document.createElement("script");s.src="https://agentbase.vn/embed.min.js";s.id="YOUR_AGENT_ID";s.domain="agentbase.vn";document.body.appendChild(s)};if(document.readyState==="complete"){onLoad()}else{window.addEventListener("load",onLoad)}})();`;
        document.body.appendChild(s);
      }, []);
      return null;
    }
    ```

    Import và thêm vào `App.tsx`:

    ```tsx theme={null}
    import { AgentbaseWidget } from './AgentbaseWidget';

    export default function App() {
      return (
        <>
          {/* nội dung ứng dụng */}
          <AgentbaseWidget />
        </>
      );
    }
    ```
  </Tab>
</Tabs>

### Widget JavaScript API

Sau khi nhúng, bạn có thể điều khiển widget qua JavaScript:

```javascript theme={null}
window.agentbase("open"); // Mở cửa sổ chat
window.agentbase("close"); // Đóng cửa sổ chat
window.agentbase("toggle"); // Toggle mở/đóng
window.agentbase("getState"); // Trả về 'open' hoặc 'closed'
```

<Info>
  Các lệnh gọi trước khi widget load xong sẽ được đưa vào hàng đợi và thực thi
  tự động khi widget sẵn sàng.
</Info>

***

## Triển khai Trang trợ giúp

Trang trợ giúp là một trang chat độc lập được lưu trữ trên hạ tầng của AgentBase, không cần nhúng vào website.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentbase-6e6fb39b/images/agent/deploy-help-page.png" alt="Trang trợ giúp" />
</Frame>

### Truy cập mặc định

Trang trợ giúp có sẵn tại:

```
https://agentbase.vn/{agent-id}/help
```

### Tùy chỉnh trang trợ giúp

| Tùy chọn            | Mô tả                                     |
| ------------------- | ----------------------------------------- |
| **Tiêu đề trang**   | Tên hiển thị trên tab trình duyệt         |
| **Favicon**         | Icon trang (`.ico`, `.png`)               |
| **Logo**            | Logo doanh nghiệp (phiên bản sáng và tối) |
| **Hình ảnh banner** | Ảnh header phía trên cửa sổ chat          |
| **Giao diện**       | Sáng, Tối, hoặc Theo hệ thống             |

### Tên miền tùy chỉnh

Gói Enterprise cho phép sử dụng domain riêng để trang trợ giúp xuất hiện dưới tên của doanh nghiệp (ví dụ: `support.yourcompany.com`).

***

## Tích hợp bên thứ ba

Mỗi kênh tích hợp có hướng dẫn riêng. Nhấn **"Quản lý"** trên card của kênh để xem hướng dẫn từng bước.

### Khuyến nghị triển khai

<Steps>
  <Step title="Bắt đầu với Chat Widget">
    Triển khai Chat Widget trước — thiết lập nhanh nhất và đạt được phạm vi
    tiếp cận rộng nhất trên website.
  </Step>

  <Step title="Tối ưu một kênh trước khi mở rộng">
    Đảm bảo agent hoạt động tốt trên Chat Widget trước khi thêm các kênh
    khác như Zalo OA hay Messenger.
  </Step>

  <Step title="Tùy chỉnh prompt theo kênh">
    Mỗi kênh có đặc thù riêng — người dùng Zalo OA thường dùng ngôn ngữ khác
    với người chat trên website. Viết channel prompt phù hợp.
  </Step>

  <Step title="Test kỹ trước khi ra mắt">
    Thử nghiệm đầy đủ trước khi thông báo cho khách hàng biết về kênh mới.
  </Step>
</Steps>

### Xử lý sự cố

| Vấn đề                          | Giải pháp                                                        |
| ------------------------------- | ---------------------------------------------------------------- |
| Không thấy bong bóng chat       | Kiểm tra mã nhúng, xem console trình duyệt                       |
| Bubble hiện nhưng không mở được | Kiểm tra CSS có xung đột `z-index` không                         |
| Agent không trả lời             | Kiểm tra agent đã bật (Hoạt động) và có nguồn dữ liệu            |
| Lỗi CORS                        | Đảm bảo domain đã được thêm vào danh sách cho phép trong cài đặt |