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

# Zalo OA

> Kết nối Zalo Official Account với AI agent để tự động trả lời tin nhắn khách hàng, và cho phép nhân viên tiếp nhận bất kỳ lúc nào.

Khi kết nối Zalo Official Account với một agent, mọi tin nhắn khách gửi đến OA sẽ được AI trả lời tự động bằng dữ liệu bạn đã huấn luyện. Nhân viên của bạn có thể tiếp nhận bất kỳ cuộc trò chuyện nào — AI sẽ tự động im lặng để không nói chồng lên nhân viên.

<Info>
  Kênh Zalo OA yêu cầu gói **Standard** trở lên. Trên gói Free, nút kết nối sẽ
  hiện hộp thoại nâng cấp.
</Info>

## Trước khi bắt đầu

Bạn cần:

* Một **Zalo Official Account** đã được xác thực, mà bạn có quyền quản trị
* Một agent đã được huấn luyện dữ liệu

<Warning>
  Mỗi Zalo OA chỉ kết nối được với **một** agent. Nếu OA đã được kết nối ở nơi
  khác, bạn cần ngắt kết nối trước.
</Warning>

## Kết nối Zalo OA

<Steps>
  <Step title="Mở trang Zalo OA">
    Vào agent → **Triển khai** → chọn thẻ **Zalo OA**.
  </Step>

  <Step title="Nhấn Kết nối">
    Nhấn **"Kết nối Zalo OA"**. Bạn sẽ được chuyển sang Zalo để cấp quyền.
  </Step>

  <Step title="Cấp quyền trên Zalo">
    Zalo hiển thị danh sách Official Account bạn quản trị. Chọn OA muốn kết
    nối và đồng ý cấp quyền nhắn tin.
  </Step>

  <Step title="Xác nhận">
    Sau khi quay lại AgentBase, hộp thoại **"Xác nhận kết nối"** hiện tên và
    ảnh đại diện của OA. Nhấn **"Kết nối"** để hoàn tất.
  </Step>

  <Step title="Kiểm tra">
    Nhắn thử một tin vào OA từ một tài khoản Zalo khác. Agent sẽ trả lời sau
    vài giây.
  </Step>
</Steps>

## Quản lý OA đã kết nối

| Thao tác            | Cách làm                             | Kết quả                                                                     |
| ------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| **Tạm dừng OA**     | Tắt công tắc bên cạnh tên OA         | AI ngừng trả lời, nhưng tin nhắn khách **vẫn được ghi lại** trong Hoạt động |
| **Đổi agent**       | Menu **"..."** → **"Gán cho agent"** | Chuyển OA sang một agent khác trong cùng workspace                          |
| **Ngắt kết nối**    | Menu **"..."** → **"Ngắt kết nối"**  | Ngừng trả lời tin nhắn từ OA. Lịch sử trò chuyện được giữ nguyên            |
| **Kết nối OA khác** | Nút **"Kết nối OA khác"**            | Thêm OA thứ hai vào cùng agent                                              |

<Info>
  Tạm dừng khác với ngắt kết nối: khi tạm dừng, bạn vẫn thấy tin nhắn khách
  trong Chat logs và vẫn trả lời thủ công được.
</Info>

### Khi hiện "Cần kết nối lại"

Quyền truy cập Zalo có hạn sử dụng và được AgentBase tự động gia hạn nền. Nếu
việc gia hạn thất bại — thường do bạn gỡ ứng dụng khỏi OA, hoặc mất quyền quản
trị — OA sẽ hiện biểu ngữ đỏ. Nhấn **"Kết nối lại"** và thực hiện lại các bước
cấp quyền.

## Nhân viên tiếp nhận cuộc trò chuyện

Có **ba cách** để nhân viên tiếp quản một cuộc trò chuyện. Cách nào cũng khiến
AI ngừng trả lời cuộc đó.

<AccordionGroup>
  <Accordion title="Trả lời từ Chat logs">
    Vào **Hoạt động** → **Chat logs**, chọn cuộc trò chuyện, rồi nhập vào ô
    **"Trả lời với tư cách nhân viên hỗ trợ"** ở cuối trang. Tin nhắn được
    gửi thẳng tới khách trên Zalo.

    Lần trả lời đầu tiên sẽ tự động tạm dừng AI.
  </Accordion>

  <Accordion title="Nhấn Tạm dừng AI">
    Nhấn **"Tạm dừng AI"** ở góc trên bên phải cuộc trò chuyện. Dùng khi bạn
    muốn đọc kỹ trước khi trả lời, hoặc muốn chắc chắn AI không xen vào.
  </Accordion>

  <Accordion title="Trả lời từ ứng dụng Zalo OA">
    Nếu bạn trả lời khách trực tiếp trong ứng dụng Zalo OA, AgentBase nhận
    biết và tự động tạm dừng AI. Tin nhắn đó cũng xuất hiện trong Chat logs
    với nhãn **"Nhân viên hỗ trợ"**, nên lịch sử không bị chia đôi.
  </Accordion>
</AccordionGroup>

### AI tự hoạt động lại sau 30 phút

Việc tạm dừng chỉ kéo dài **30 phút**, sau đó AI tự trả lời trở lại. Điều này
tránh trường hợp nhân viên quên bật lại và khách bị bỏ quên.

Nhấn **"Tiếp tục AI"** nếu bạn muốn giao lại ngay cho agent.

<Info>
  Riêng khi khách **chủ động yêu cầu gặp người thật**, AI sẽ dừng vô thời hạn
  cho tới khi bạn nhấn **"Giải quyết"** — người đang xếp hàng chờ nhân viên
  không nên bị bot cắt ngang.
</Info>

## Giới hạn thời gian gửi tin của Zalo

Zalo cho phép OA gửi tin nhắn tư vấn qua API trong vòng **7 ngày** kể từ tương
tác gần nhất của khách. Nếu bạn trả lời một cuộc trò chuyện cũ hơn, AgentBase sẽ
báo lỗi ngay thay vì gửi đi rồi thất bại.

<Warning>
  Đây là quy định của Zalo, không phải giới hạn của AgentBase.
</Warning>

**Về chi phí:** tin tư vấn gửi trong **48 giờ đầu** kể từ tương tác cuối của
khách là miễn phí, và hạn mức miễn phí được đặt lại mỗi khi khách tương tác mới.
Sau 48 giờ nhưng vẫn trong 7 ngày, tin vẫn gửi được nhưng **Zalo tính phí** theo
bảng giá của họ. Agent trả lời tự động luôn nằm trong khung miễn phí — chỉ khi
nhân viên trả lời một cuộc trò chuyện đã cũ vài ngày thì mới phát sinh phí.

**Quá 7 ngày:** trả lời trực tiếp trong **ứng dụng Zalo OA**, hoặc dùng loại tin
nhắn khác do Zalo quy định (tin truyền thông, tin giao dịch) từ chính công cụ
của Zalo.

## Tin nhắn và tín dụng

* Mỗi câu trả lời của AI tiêu tốn **một tín dụng**
* Nếu khách gửi liên tiếp nhiều tin, AgentBase **gộp lại thành một câu trả lời**
  và chỉ tính một tín dụng
* Tin nhắn do nhân viên trả lời **không tốn tín dụng**
* Khi hết tín dụng, AI ngừng trả lời nhưng tin nhắn khách vẫn được ghi lại

## Hình ảnh, sticker và tệp đính kèm

Khi khách gửi hình ảnh, sticker, tệp hoặc vị trí, cuộc trò chuyện vẫn hiện trong
Chat logs kèm ghi chú về loại nội dung. Agent **không đọc được** nội dung đó, nên
sẽ gửi một câu ngắn đề nghị khách mô tả thêm bằng văn bản — câu này **không tốn
tín dụng**, và chỉ gửi một lần cho mỗi loạt tin đính kèm.

Nội dung gốc (ảnh, tệp, vị trí…) **chỉ xem được trong ứng dụng Zalo OA** — Zalo
gửi cho AgentBase thông tin về sự kiện chứ không gửi kèm tệp.

## Xử lý sự cố

<AccordionGroup>
  <Accordion title="Đã kết nối nhưng agent không trả lời">
    Kiểm tra theo thứ tự: công tắc của OA có đang bật không, gói dịch vụ có
    còn hiệu lực không, workspace có còn tín dụng không, và cuộc trò chuyện
    có đang ở trạng thái tạm dừng AI không.
  </Accordion>

  <Accordion title="OA này đã được kết nối với tài khoản khác">
    Mỗi OA chỉ thuộc về một agent trên toàn hệ thống. Hãy ngắt kết nối ở nơi
    cũ trước khi kết nối lại.
  </Accordion>

  <Accordion title="Không đọc được thông tin Official Account">
    Xảy ra khi tài khoản Zalo bạn dùng để đăng nhập không phải quản trị viên
    của OA, hoặc OA chưa được xác thực. Hãy kiểm tra lại trong Zalo OA
    Manager rồi kết nối lại.
  </Accordion>

  <Accordion title="Tin nhắn hiện trong Chat logs nhưng khách không nhận được">
    Thường do đã quá 7 ngày kể từ tương tác cuối của khách, hoặc quyền truy
    cập đã hết hạn. Kiểm tra biểu ngữ "Cần kết nối lại" ở trang Zalo OA.
  </Accordion>
</AccordionGroup>