Cấu hình Zalo

Bestie có adapter Zalo đầu tiên để chạy runtime local qua API kiểu bot của Zalo. Adapter này cố tình giữ scope hẹp: chỉ text, chỉ owner, polling local, memory controls và approval prompts.

Dùng Telegram nếu hiện tại bạn cần attachments hoặc voice workflows. Dùng Zalo nếu bạn muốn đưa cùng runtime Bestie vào chat Zalo và chấp nhận adapter text-only ở giai đoạn này.

Trạng thái hiện tại

Zalo adapter hiện hỗ trợ:

• Polling local bằng bestie channels zalo hoặc polling một lần bằng bestie channels zalo --once.
• Setup bằng bestie channels zalo setup.
• Chỉ cho owner qua channels.zalo.ownerUserId.
• Tin nhắn text và text caption.
• Typing indicators nếu platform call thành công.
• Tách reply dài thành các đoạn 2.000 ký tự.
• Memory recall và memory reasoning cho channel zalo.
• Progress message khi dùng tool và pending action approvals.
• Slash commands: /help, /status, /providers, /approvals, /approve <id>, /deny <id>, /memory, /memory pending, /memory pause, và /memory resume.
• Ghi log transcript để debug tương tác Zalo.
• Trích xuất sender/chat ID linh hoạt cho nhiều định dạng response API Zalo khác nhau.

Chưa hỗ trợ:

• Attachments, ảnh, file, audio hoặc voice workflow.
• Rich message templates của Zalo.
• Chính sách group phức tạp ngoài owner id đã cấu hình.
• Webhook hosting; adapter hiện tại poll từ local process.

Cần chuẩn bị

• Bestie local đã setup ổn và bestie doctor pass cho LLM provider.
• Zalo bot token tương thích với Zalo Bot API calls của Bestie.
• Zalo owner user id của bạn.

Secrets nằm trong .bestie/.env; channel settings không phải secret nằm trong .bestie/config.json.

Chạy setup

bestie channels zalo setup

Wizard hỏi:

1. Owner Zalo user id.
2. Zalo bot token.

Nó ghi owner id và tên biến môi trường token vào config:

{
  "channels": {
    "zalo": {
      "enabled": true,
      "botTokenEnv": "BESTIE_ZALO_BOT_TOKEN",
      "ownerUserId": "zalo-owner-1"
    }
  }
}

Giá trị token được lưu trong .bestie/.env:

BESTIE_ZALO_BOT_TOKEN=your-zalo-token

Chạy Zalo polling

Chạy polling loop local:

bestie channels zalo

Để smoke check, xử lý một polling batch rồi thoát:

bestie channels zalo --once

Bestie chỉ reply khi sender id của message khớp channels.zalo.ownerUserId. Message từ người khác sẽ bị ignore.

Ghi log transcript

Để debug tương tác Zalo, bạn có thể bật ghi log transcript:

bestie channels zalo --transcript ./logs/zalo-smoke.jsonl

File JSONL sẽ ghi lại:

• Sự kiện zalo_get_updates_start / zalo_get_updates_finish cho mỗi chu kỳ polling.
• Sự kiện zalo_send_message cho tin nhắn gửi đi.
• Sự kiện zalo_send_chat_action cho typing indicators.

Mỗi mục bao gồm timestamps và identifier đã hash để bảo mật.

Capture API response shapes

Để debug các định dạng response API Zalo không mong đợi:

bestie channels zalo --transcript ./logs/zalo-smoke.jsonl --capture-shape

Tùy chọn này capture cấu trúc của responses getUpdates, hữu ích khi tích hợp với các phiên bản Zalo Bot API khác nhau.

Commands trong Zalo

Dùng các lệnh này từ owner account đã cấu hình:

/help
/status
/providers
/memory
/memory pending
/memory pause
/memory resume
/approvals
/approve <id>
/deny <id>

Approval request được queue local. Khi Bestie cần quyền cho một action có gate, nó gửi approval id trong Zalo. Reply /approve <id> hoặc /deny <id> để xử lý.

Troubleshooting

• Zalo is not enabled: chạy bestie channels zalo setup trước.
• Zalo bot token env ... is missing: thêm BESTIE_ZALO_BOT_TOKEN vào .bestie/.env hoặc chạy lại setup.
• Zalo owner user id is missing: set channels.zalo.ownerUserId trong .bestie/config.json.
• Bestie không reply: kiểm tra sender id có khớp chính xác ownerUserId; message không phải owner bị ignore theo thiết kế.
• Provider timeout khi xử lý Zalo: chạy bestie doctor, hỏi câu hẹp hơn hoặc tăng llm.timeoutMs.
• Polling lỗi: kiểm tra token, network và endpoint Zalo Bot API có reachable từ máy bạn không.
• Lỗi response shape không mong đợi: chạy với flag --capture-shape để log cấu trúc API response để debug.

Kiểm tra runtime core bằng:

bestie doctor
bestie status

Validation từ source

Khi làm trong Bestie source repository, các lệnh này cover đường setup Zalo:

npm run smoke:zalo:setup
npm test