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

> Kết nối Official Account để Agent tự động trả lời tin nhắn của khách trên Zalo

Kênh Zalo nối một Official Account với Agent. Sau khi kết nối, mọi tin nhắn khách gửi tới Official Account sẽ được Agent trả lời tự động.

<Info icon="comment-dots">
  Bảng cấu hình mở từ tab **Channels**, bấm vào kênh **Zalo**. Tiêu đề bảng là "Zalo configuration".
</Info>

<img src="https://mintcdn.com/fpt-62e894b4/ia7V2FSrpeYV4o83/images/zl_config.jpg?fit=max&auto=format&n=ia7V2FSrpeYV4o83&q=85&s=514802d5434ff94c1e14167beade0eb0" alt="Bảng cấu hình Zalo" width="1568" height="706" data-path="images/zl_config.jpg" />

## Chuẩn bị trước khi kết nối

Bạn cần quyền quản trị trên Zalo Official Account và ứng dụng Zalo tương ứng, cùng ba thông tin bí mật:

| Thông tin | Lấy ở đâu |
| - | - |
| **OA Secret Key** | Mục Webhook của Official Account |
| **App Secret** | Phần thiết lập ứng dụng trên Zalo, không phải trang quản trị OA |
| **Refresh Token** | Luồng cấp quyền OAuth của ứng dụng |

<Warning>
  Nhập sai bất kỳ thông tin nào trong ba thông tin trên thì kết nối sẽ thất bại và mọi tin nhắn gửi đến đều bị từ chối. Hãy sao chép nguyên văn, không thêm dấu cách ở đầu hoặc cuối.
</Warning>

## Khai báo Webhook trên Zalo

Ô **Webhook URL** ở đầu bảng là ô chỉ đọc, kèm nút sao chép:

```text theme={null}
https://console-agents.fpt.ai/webhooks/zalo
```

<Steps>
  <Step title="Sao chép Webhook URL">
    Bấm nút sao chép bên cạnh ô.
  </Step>

  <Step title="Dán vào ứng dụng Zalo">
    Mở ứng dụng Zalo của bạn, dán vào ô Webhook.
  </Step>

  <Step title="Lưu lại trên Zalo">
    Lưu thiết lập webhook trước khi quay về Console.
  </Step>
</Steps>

<Note>
  Một địa chỉ webhook phục vụ mọi Official Account. Hệ thống phân biệt các tài khoản bằng OA ID có trong dữ liệu Zalo gửi về, nên bạn không cần địa chỉ riêng cho từng OA.
</Note>

## Các trường cần điền

| Trường | Bắt buộc | Mô tả |
| - | - | - |
| **Webhook URL** | Chỉ đọc | Địa chỉ nhận dữ liệu từ Zalo, sao chép sang ứng dụng Zalo |
| **App ID** | Có | Mã định danh ứng dụng Zalo. Không phải thông tin bí mật, nhưng là căn cứ để xác thực tin nhắn gửi đến |
| **App Secret** | Có | Lấy từ phần thiết lập ứng dụng trên Zalo, không phải trang quản trị OA. Hiển thị dạng che dấu |
| **OA Secret Key** | Có | Khóa bí mật của Official Account, dùng để xác thực webhook. Hiển thị dạng che dấu |
| **Refresh Token** | Có | Lấy từ luồng cấp quyền OAuth. Zalo cấp token mới sau mỗi lần sử dụng, hệ thống luôn lưu token mới nhất. Hiển thị dạng che dấu |
| **Display name** | Không | Tên hiển thị của kênh. Để trống thì hệ thống dùng tên Official Account do Zalo trả về |

## Kết nối Official Account

<Steps>
  <Step title="Mở kênh Zalo">
    Vào tab **Channels**, bấm vào kênh **Zalo** đang ở trạng thái Not configured.
  </Step>

  <Step title="Khai báo webhook trên Zalo">
    Sao chép Webhook URL và dán vào ứng dụng Zalo như hướng dẫn ở trên.
  </Step>

  <Step title="Điền App ID, App Secret, OA Secret Key và Refresh Token">
    Dán nguyên văn từng giá trị vào đúng ô tương ứng.
  </Step>

  <Step title="Đặt tên hiển thị nếu cần">
    Nhập **Display name**, hoặc để trống để dùng tên Official Account.
  </Step>

  <Step title="Bấm Connect">
    Hệ thống kiểm tra thông tin với Zalo. Kết nối thành công thì trạng thái kênh chuyển khỏi Not configured.
  </Step>
</Steps>

## Sửa thông tin kết nối

Mở lại kênh Zalo từ tab Channels. Các ô bí mật hiển thị dạng che dấu; nhập giá trị mới để thay thế, để nguyên nếu không đổi. Bấm **Connect** để lưu lại, hoặc **Cancel** để đóng bảng mà không lưu.

<Tip>
  Refresh Token được Zalo cấp mới sau mỗi lần sử dụng. Nếu kênh bỗng ngừng trả lời, hãy lấy Refresh Token mới từ luồng OAuth và cập nhật lại tại đây.
</Tip>

## Ngắt kết nối

Có hai cách dừng phục vụ trên Zalo:

<CardGroup cols={2}>
  <Card title="Tắt kênh khi xuất bản" icon="toggle-off">
    Mở hộp thoại **Publish**, bỏ tích **Zalo** trong phần External channels rồi xuất bản. Thông tin kết nối vẫn được giữ.
  </Card>

  <Card title="Ngắt kết nối hẳn" icon="link-slash">
    Mở bảng cấu hình Zalo và ngắt kết nối. Thông tin bí mật bị xóa, khi cần dùng lại bạn phải nhập từ đầu.
  </Card>
</CardGroup>

<Warning>
  Sau khi ngắt kết nối, khách nhắn tới Official Account sẽ không được Agent trả lời nữa. Hãy chuẩn bị phương án trực tin nhắn thủ công trước khi ngắt.
</Warning>

## Xử lý sự cố thường gặp

| Hiện tượng | Nguyên nhân thường gặp | Cách xử lý |
| - | - | - |
| Bấm Connect nhưng báo lỗi | Sai App Secret, OA Secret Key hoặc Refresh Token | Lấy lại đúng giá trị từ Zalo và dán lại |
| Kết nối thành công nhưng không nhận tin nhắn | Chưa khai báo Webhook URL trên ứng dụng Zalo | Sao chép lại Webhook URL và lưu trên Zalo |
| Khách nhận thông báo "This conversation is unavailable" | Agent chưa xuất bản, hoặc kênh Zalo chưa được tích khi xuất bản | Xem [Xuất bản](/publish-agent) |
| Kênh đang chạy rồi bỗng ngừng trả lời | Refresh Token đã hết hiệu lực | Cập nhật Refresh Token mới |

<Info icon="tower-broadcast">
  Xem trạng thái tổng thể của mọi kênh và đổi phiên bản đang phục vụ tại [Quản lý kênh triển khai](/quan-ly-kenh-trien-khai).
</Info>


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