Kết nối Zalo OA
Thêm kết nối Zalo Official Account bằng app/oa/token, nhận webhook và trả lời khách qua API Zalo OA.
Zalo OA (Official Account) là kênh chính thức của doanh nghiệp trên Zalo. Kết nối OA khác tài khoản cá nhân ở chỗ không có phiên socket — nó stateless, chỉ cần thông tin app, OA và token.
Thông tin cần có
Một Zalo connection loại zalo_oa được khoá theo oa_id và cần:
| Trường | Dùng để |
|---|---|
app_id | Định danh ứng dụng Zalo dùng chung với OA. |
oa_id | Định danh Official Account — khoá tra connection. |
secret | Bí mật OA, dùng xác thực chữ ký webhook. |
access_token | Token gọi API gửi tin của Zalo. |
Không chia sẻ secret và token
secret và access_token là thông tin xác thực. Không dán chúng vào chat, tài liệu hay ảnh
chụp màn hình.
Luồng tin nhắn
Zalo OA hoạt động theo webhook (không phải socket như Zalo cá nhân):
- Khách gửi tin cho OA.
- Zalo gọi webhook của hệ thống kèm header chữ ký.
- Hệ thống xác thực chữ ký, parse sự kiện, rồi dispatch workflow đã bind.
- Phản hồi được gửi lại qua API Zalo OA.
Xác thực chữ ký webhook
Header X-ZEvent-Signature có dạng mac=<hex>, được tính bằng:
sha256(app_id + raw_body + timestamp + secret)
Dùng raw body nguyên vẹn
Chữ ký tính trên raw body trước khi parse JSON. Nếu bạn parse rồi stringify lại, chữ ký sẽ sai và webhook bị từ chối.
Sự kiện được xử lý
Hiện hệ thống chỉ nhận sự kiện user_send_text — tin nhắn văn bản do người dùng gửi. Sự kiện
khác bị bỏ qua. Một inbound hợp lệ cần có oa_id, người gửi (user_id), nội dung text và
msg_id.
Gửi tin trả lời
Phản hồi được gửi qua endpoint tin tư vấn (customer service) của Zalo OA, gửi tới user_id của
người gửi. Nội dung text rỗng sẽ không gửi.
Gán bot vào kết nối
Giống mọi kết nối Zalo, bot chỉ chạy khi có Workflow binding đang bật. Xem Workflow & Kịch bản AI để biết cách publish và gán workflow.