Zalo (Bot API)

Trạng thái: thử nghiệm. Hiện chỉ hỗ trợ tin nhắn trực tiếp; nhóm sẽ được hỗ trợ sớm theo tài liệu Zalo.

Cần cài Plugin

Zalo được cung cấp dưới dạng plugin và không đi kèm với bản cài đặt core.

• Cài qua CLI: openclaw plugins install @openclaw/zalo
• Hoặc chọn Zalo trong quá trình onboarding và xác nhận cài đặt
• Chi tiết: Plugins

Cài đặt nhanh (dành cho người mới)

1. Cài plugin Zalo:
   • Từ source checkout: openclaw plugins install ./extensions/zalo
   • Từ npm (nếu đã publish): openclaw plugins install @openclaw/zalo
   • Hoặc chọn Zalo khi onboarding và xác nhận cài đặt
2. Thiết lập token:
   • Env: ZALO_BOT_TOKEN=...
   • Hoặc config: channels.zalo.botToken: "...".
3. Khởi động lại Gateway (hoặc hoàn tất onboarding).
4. Truy cập DM mặc định là pairing; phê duyệt mã pairing khi có liên hệ đầu tiên.

Config tối thiểu:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Zalo là gì

Zalo là ứng dụng nhắn tin phổ biến tại Việt Nam; Bot API của nó cho phép Gateway chạy bot để trò chuyện 1:1. Phù hợp cho hỗ trợ khách hàng hoặc thông báo khi các bạn muốn routing xác định về Zalo.

• Một Channel Zalo Bot API do Gateway quản lý.
• Routing xác định: tin nhắn trả lời luôn quay về Zalo; model không bao giờ tự chọn channel.
• DM chia sẻ Session chính của Agent.
• Nhóm chưa được hỗ trợ (tài liệu Zalo ghi “sắp ra mắt”).

Cài đặt (hướng dẫn nhanh)

1) Tạo bot token (Zalo Bot Platform)

1. Truy cập https://bot.zaloplatforms.com và đăng nhập.
2. Tạo bot mới và cấu hình các thiết lập.
3. Copy bot token (định dạng: 12345689:abc-xyz).

2) Cấu hình token (env hoặc config)

Ví dụ:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

Tùy chọn env: ZALO_BOT_TOKEN=... (chỉ hoạt động cho tài khoản mặc định).

Hỗ trợ nhiều tài khoản: dùng channels.zalo.accounts với token riêng cho từng tài khoản và name tùy chọn.

3. Khởi động lại Gateway. Zalo sẽ bắt đầu khi token được xác định (env hoặc config).
4. Truy cập DM mặc định là pairing. Phê duyệt mã khi bot được liên hệ lần đầu.

Cách hoạt động

• Tin nhắn đến được chuẩn hóa vào channel envelope chung với media placeholders.
• Tin nhắn trả lời luôn routing về cùng chat Zalo đó.
• Mặc định dùng long-polling; chế độ webhook có sẵn với channels.zalo.webhookUrl.

Giới hạn

• Text gửi đi được chia nhỏ thành 2000 ký tự (giới hạn API Zalo).
• Download/upload media bị giới hạn bởi channels.zalo.mediaMaxMb (mặc định 5).
• Streaming bị chặn mặc định do giới hạn 2000 ký tự khiến streaming ít hữu ích hơn.

Kiểm soát truy cập (DM)

Truy cập DM

• Mặc định: channels.zalo.dmPolicy = "pairing". Người gửi lạ sẽ nhận mã pairing; tin nhắn bị bỏ qua cho đến khi được phê duyệt (mã hết hạn sau 1 giờ).
• Phê duyệt qua:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Pairing là cơ chế trao đổi token mặc định. Chi tiết: Pairing
• channels.zalo.allowFrom chấp nhận user ID dạng số (không có tính năng tra cứu username).

Long-polling vs webhook

• Mặc định: long-polling (không cần URL công khai).
• Chế độ webhook: thiết lập channels.zalo.webhookUrl và channels.zalo.webhookSecret.
  • Webhook secret phải dài 8-256 ký tự.
  • Webhook URL phải dùng HTTPS.
  • Zalo gửi events với header X-Bot-Api-Secret-Token để xác thực.
  • Gateway HTTP xử lý webhook requests tại channels.zalo.webhookPath (mặc định là path của webhook URL).

Lưu ý: getUpdates (polling) và webhook loại trừ lẫn nhau theo tài liệu API Zalo.

Các loại tin nhắn được hỗ trợ

• Tin nhắn text: Hỗ trợ đầy đủ với chia nhỏ 2000 ký tự.
• Tin nhắn hình ảnh: Download và xử lý ảnh đến; gửi ảnh qua sendPhoto.
• Stickers: Được ghi log nhưng chưa xử lý đầy đủ (không có phản hồi từ Agent).
• Loại không hỗ trợ: Được ghi log (ví dụ: tin nhắn từ người dùng được bảo vệ).

Khả năng

Delivery targets (CLI/cron)

• Dùng chat id làm target.
• Ví dụ: openclaw message send --channel zalo --target 123456789 --message "hi".

Troubleshooting

Bot không phản hồi:

• Kiểm tra token có hợp lệ không: openclaw channels status --probe
• Xác minh người gửi đã được phê duyệt (pairing hoặc allowFrom)
• Check Gateway logs: openclaw logs --follow

Webhook không nhận events:

• Đảm bảo webhook URL dùng HTTPS
• Xác minh secret token dài 8-256 ký tự
• Xác nhận Gateway HTTP endpoint có thể truy cập được trên path đã cấu hình
• Kiểm tra getUpdates polling không đang chạy (chúng loại trừ lẫn nhau)

Tham khảo cấu hình (Zalo)

Cấu hình đầy đủ: Configuration

Các tùy chọn provider:

• channels.zalo.enabled: bật/tắt khởi động channel.
• channels.zalo.botToken: bot token từ Zalo Bot Platform.
• channels.zalo.tokenFile: đọc token từ file path.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing).
• channels.zalo.allowFrom: DM allowlist (user IDs). open yêu cầu "*". Wizard sẽ hỏi numeric IDs.
• channels.zalo.mediaMaxMb: giới hạn media đến/đi (MB, mặc định 5).
• channels.zalo.webhookUrl: bật chế độ webhook (yêu cầu HTTPS).
• channels.zalo.webhookSecret: webhook secret (8-256 ký tự).
• channels.zalo.webhookPath: webhook path trên Gateway HTTP server.
• channels.zalo.proxy: proxy URL cho API requests.

Tùy chọn nhiều tài khoản:

• channels.zalo.accounts.<id>.botToken: token riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.tokenFile: token file riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.name: tên hiển thị.
• channels.zalo.accounts.<id>.enabled: bật/tắt tài khoản.
• channels.zalo.accounts.<id>.dmPolicy: DM policy riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.allowFrom: allowlist riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.webhookUrl: webhook URL riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.webhookSecret: webhook secret riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.webhookPath: webhook path riêng cho từng tài khoản.
• channels.zalo.accounts.<id>.proxy: proxy URL riêng cho từng tài khoản.