Kết nối một Zalo OA
Nối một Official Account của Zalo vào workspace: khai app, dán webhook, cấp quyền để lấy cặp token, và biết trước cửa sổ thời gian được phép gửi.
Zalo cần nhiều bước hơn các kênh khác vì hai đầu phải khớp nhau: ứng dụng trên developers.zalo.me và kênh trong console. Trang này đi theo đúng thứ tự đó.
Mục tiêu
Một kênh Zalo có cặp token còn hiệu lực, nhận được tin khách nhắn cho OA và gửi trả lời ra được.
Trước khi bắt đầu
- Tài khoản của bạn phải được ghi trên kênh; Vai trò và quyền theo tính năng nói ai có quyền đó.
- Một ứng dụng của bạn trên developers.zalo.me, là trang của bên thứ ba, cùng App ID và App Secret Key của nó.
- OA Secret Key của Official Account, lấy trong phần cài đặt OA, ngay cạnh ô Webhook URL.
- Người đang giữ quyền admin của OA, vì bước cấp quyền do họ bấm.
Các bước
Ở cột trái bấm Kênh, bấm Thêm Kênh, rồi chọn ô Zalo OA.
Điền Tên kênh, App ID và App Secret Key. Không cần nhập ID Official Account: hệ thống đọc giá trị đó từ token sau khi kết nối.
Bấm Tạo tiện ích. Màn Thành công! hiện URL Webhook; bấm Sao chép.
Dán URL đó vào phần Webhook của ứng dụng trên developers.zalo.me, rồi bật các sự kiện tin nhắn bạn muốn nhận.
Quay lại danh sách Kênh, mở kênh vừa tạo và chọn tab Cấu hình Zalo OA.
Điền OA Secret Key rồi bấm Lưu cài đặt. Đây là khoá Zalo dùng để ký mọi sự kiện webhook, khác với App Secret Key ở trên.
Ở mục Access token, bấm Tạo code challenge. Khai Callback URL và Code challenge vừa hiện vào trang cài đặt ứng dụng.
Gửi đường dẫn cấp quyền do Zalo sinh ra cho admin của OA. Họ bấm cho phép thì Zalo chuyển hướng về console và cặp token được lưu tự động.
Đường thứ hai, khi bạn quản trị cả ứng dụng lẫn OA: lấy refresh token trong API Explorer, dán vào ô Refresh token ở Cách 2 rồi bấm Kết nối.
Access token của Zalo sống 25 giờ và được làm mới tự động trước khi hết hạn. Refresh token dùng một lần, xoay vòng sau mỗi lần làm mới, và hết hạn sau ba tháng. Một OA nào không hoạt động quá ba tháng thì cặp token chết hẳn và bạn phải cấp quyền lại từ bước bảy.
Zalo giới hạn cửa sổ thời gian được phép gửi. Tin tư vấn chỉ gửi được trong bảy ngày kể từ lần khách tương tác gần nhất với OA, và không gửi được cho người chưa từng tương tác. Ngoài cửa sổ đó, một hội thoại cũ trong hàng đợi vẫn mở nhưng nhân viên không trả lời ra ngoài được.
Kiểm chứng
Ở tab Cấu hình Zalo OA, thẻ trạng thái dưới Access token phải đọc Còn hiệu lực, kèm dòng Hết hạn với thời điểm cụ thể. Ô ID Official Account cũng đã tự điền.
Nhắn một câu cho OA từ ứng dụng Zalo. Câu đó phải hiện trong hàng đợi Trò chuyện, và câu trả lời bạn gửi từ console phải về được máy khách.
Sự cố thường gặp
| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Thẻ trạng thái là Lỗi, kèm một câu của Zalo | Refresh token đã hỏng hoặc đã bị dùng ở nơi khác | Lấy refresh token mới rồi bấm Kết nối |
| Thẻ là Chưa kết nối dù đã cấp quyền | Cấp quyền chưa hoàn tất, hoặc callback trỏ sai chỗ | Kiểm tra Callback URL trên trang ứng dụng, rồi cấp quyền lại |
| Khách nhắn mà hàng đợi không có gì | Thiếu OA Secret Key, nên sự kiện đến bị loại vì sai chữ ký | Điền khoá đó rồi bấm Lưu cài đặt |
| Cấp quyền thất bại ngay sau khi tạo challenge mới | Trang ứng dụng vẫn giữ challenge cũ | Khai lại giá trị mới trên developers.zalo.me |
| Gửi hỏng: người dùng không tương tác trong bảy ngày qua | Cửa sổ gửi đã đóng | Chờ khách nhắn lại; không có cách mở lại từ console |
| Gửi hỏng: người dùng chưa quan tâm Official Account | Khách chưa theo dõi OA | Mời khách quan tâm OA rồi nhắn lại |
| Gửi hỏng trong khoảng 22 giờ đến 6 giờ sáng | Zalo chặn loại tin đó theo khung giờ | Gửi lại sau 6 giờ sáng |