Bài 2 — Thiết lập Zalo OA và lấy khóa kết nối cho agent

Để agent "nghe" và "nói" trên Zalo, bạn cần một Zalo Official Account (OA) đã xác thực và một Zalo App trên Zalo for Developers. Nhiều người bỏ cuộc ngay bước này vì lẫn lộn giữa OA và App. Bài này đi từng bước rõ ràng.

Phân biệt 3 thành phần

• Zalo OA: "trang" doanh nghiệp mà khách nhắn tin tới (tạo tại oa.zalo.me).
• Zalo App: ứng dụng kỹ thuật trên developers.zalo.me để lấy app_id, secret_key, và cấp quyền OA cho agent.
• Webhook: URL mà Zalo gọi tới mỗi khi khách nhắn tin — đây là "tai" của agent.

Các bước thiết lập

• Tạo OA: vào oa.zalo.me → tạo OA doanh nghiệp → gửi giấy phép kinh doanh để xác thực (bắt buộc để dùng API gửi tin).
• Tạo App: vào developers.zalo.me → Tạo ứng dụng mới → ghi lại App ID và Secret Key.
• Liên kết OA với App: trong App → mục Official Account → thêm OA của bạn → cấp quyền.
• Lấy Access Token: Zalo dùng access_token (hết hạn ~1 giờ) + refresh_token (dài hạn). Bạn phải lưu và tự làm mới token — đây là điểm nhiều người vấp.
• Cấu hình Webhook: trong App → Webhook → dán URL endpoint của agent (ví dụ URL do n8n cấp) → chọn sự kiện user_send_text, user_send_image, follow.
• Xác minh Webhook: Zalo gửi request kiểm tra; endpoint phải phản hồi 200 và verify chữ ký X-ZEvent-Signature.

Cấu trúc một sự kiện tin nhắn Zalo gửi tới webhook

{
  "app_id": "123456",
  "sender": { "id": "user_zalo_id" },
  "recipient": { "id": "oa_id" },
  "event_name": "user_send_text",
  "message": { "text": "Cho mình hỏi giá bánh trung thu" },
  "timestamp": "1719300000000"
}

Agent sẽ đọc message.text và sender.id để biết "ai nói gì".

Gửi tin trả lời (Send Message API)

curl -X POST 'https://openapi.zalo.me/v3.0/oa/message/cs' \
  -H 'access_token: YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": { "user_id": "user_zalo_id" },
    "message": { "text": "Dạ bánh trung thu 320.000đ/hộp ạ" }
  }'

Luật quan trọng: cửa sổ 48 giờ

Zalo cho phép gửi tin nhắn tư vấn (CS) miễn phí trong 48 giờ kể từ lần cuối khách nhắn. Ngoài 48h, bạn phải dùng tin có phí hoặc ZNS (Zalo Notification Service) qua template được duyệt. Agent phải nhận biết được khách đang trong hay ngoài cửa sổ để chọn đúng loại tin.

Checklist trước khi sang bài 3

• [ ] OA đã xác thực doanh nghiệp
• [ ] Có App ID + Secret Key
• [ ] Lấy được access_token + refresh_token, đã lưu nơi an toàn
• [ ] Có cơ chế tự refresh token trước khi hết hạn
• [ ] Webhook nhận được sự kiện test (thử nhắn OA và thấy log)
• [ ] Gửi thử được 1 tin trả lời qua API

Sai lầm thường gặp

• Quên refresh token: access_token hết hạn sau ~1h, agent "chết" sau 1 giờ chạy. Phải có cron làm mới token định kỳ (ví dụ mỗi 50 phút).
• Lưu secret trong code: rò rỉ secret_key = ai cũng gửi tin thay bạn. Dùng biến môi trường/credential store.
• Không verify chữ ký webhook: kẻ xấu giả request. Luôn kiểm tra X-ZEvent-Signature bằng mac = sha256(app_id + data + timestamp + oa_secret).
• Nhầm gửi tin ngoài 48h bằng API CS: bị lỗi/không gửi được. Phải dùng ZNS template.
• Chưa xác thực OA đã vội gọi API: nhiều endpoint bị chặn với OA chưa xác thực.

Bài sau: chọn nền tảng no-code (n8n) và dựng luồng tiếp nhận tin nhắn đầu tiên.