Zalo API: OA, ZNS, Zalo Bot và cách nối Zalo cá nhân với phần mềm
Cập nhật 2026-11-09 · biên soạn bởi đội ZaloDesk
Zalo có API cho OA, cho thông báo ZNS và cho bot, nhưng không có API cho Zalo cá nhân, nơi phần lớn khách Việt Nam nhắn tin. Chúng tôi đã nối ZaloDesk với API Zalo OA và ZNS từ đầu tới cuối, và bài này ghi lại bản đồ API cùng những chỗ dễ vấp nhất: token dùng một lần, webhook tự tắt, lịch sử chỉ lấy 10 tin mỗi lần.
Các API của Zalo
| API | Địa chỉ | Dùng cho |
|---|---|---|
| Official Account API | openapi.zalo.me | Tin tư vấn, khách hàng, nhãn, bài viết, nhóm OA, cuộc gọi, webhook |
| ZNS (ZBS Template Message) | business.openapi.zalo.me | Thông báo theo mẫu tới số điện thoại |
| Cấp quyền (OAuth) | oauth.zaloapp.com | Lấy token cho OA, đăng nhập bằng Zalo |
| Zalo Bot | bot.zaloplatforms.com | Bot chat dùng token, tách biệt với OA |
| Mini App SDK | mini.zalo.me | Ứng dụng nhỏ chạy trong Zalo |
Mọi API của OA cần Zalo OA đã xác thực. Giá từng tin thông báo ở bài bảng giá ZNS.
Cấp quyền: một ứng dụng, nhiều OA
Bạn đăng ký một ứng dụng trên trang nhà phát triển của Zalo (app_id và secret_key). Quản trị viên của từng OA cấp quyền cho ứng dụng một lần qua OAuth v4 có PKCE, chọn các nhóm quyền cần dùng: gửi tin, đọc lịch sử, quản lý khách và nhãn, bài viết, cuộc gọi, nhận sự kiện. Một ứng dụng đại diện được nhiều OA. Tên miền nhận callback và webhook phải được xác minh bằng bản ghi DNS, tệp HTML hoặc thẻ meta.
- Mã cấp quyền dùng một lần, sống 10 phút.
- Access token sống 25 giờ.
- Refresh token sống 3 tháng, dùng một lần và được thay mới mỗi lần làm mới. Hai tiến trình cùng làm mới một OA sẽ làm token của nhau hết hiệu lực, nên chỉ để một nơi giữ và làm mới token.
Webhook: trả 200 trong 2 giây
Mỗi ứng dụng có một địa chỉ webhook, bật từng loại sự kiện riêng: khách gửi tin, OA gửi tin, khách đã nhận và đã xem, quan tâm và bỏ quan tâm, khách gửi thông tin, cuộc gọi, sự kiện nhóm, trạng thái mẫu ZNS. Mỗi yêu cầu có chữ ký trong header X-ZEvent-Signature, tính bằng sha256 của app_id, nội dung, thời điểm và secret key của OA.
Zalo chờ trả 200 trong 2 giây. Lần gửi thất bại được thử lại sau 30 giây, 5, 15, 30 phút và 1 giờ, sau đó Zalo tắt webhook cho tới khi bạn đăng ký lại. Cách an toàn: nhận, kiểm chữ ký, lưu, trả 200, rồi mới xử lý. Tin nhân viên gõ trong trang quản lý OA cũng bắn sự kiện OA gửi tin kèm mã quản trị viên, nên hệ thống của bạn thấy được cả câu trả lời không đi qua API.
Giới hạn cần biết trước
- Tốc độ: 100 yêu cầu/phút mỗi OA ở gói Tăng trưởng, 2.000 ở Toàn diện, và 4.000 yêu cầu/phút cho cả ứng dụng trên mọi OA. Tin ZNS không tính vào giới hạn này.
- Cửa sổ trả lời: tin tư vấn chỉ gửi được cho khách tương tác trong 7 ngày, miễn phí trong 48 giờ. Có API kiểm tra lần tương tác gần nhất trước khi gửi.
- Lịch sử: tối đa 10 tin mỗi lần gọi, cả danh sách hội thoại gần đây lẫn lịch sử một khách, nên chỉ nên nhập các hội thoại gần.
- Danh sách khách: 50 khách mỗi lần, tối đa khoảng 10.000 khách qua phân trang.
- Mã khách: mỗi OA cấp một mã riêng cho từng khách, không trùng tài khoản Zalo cá nhân. Số điện thoại chỉ có khi khách tự gửi qua biểu mẫu xin thông tin.
- Tệp gửi đi: ảnh JPG, PNG tới 1 MB, GIF tới 5 MB, tệp PDF, DOC, DOCX, CSV tới 5 MB.
Zalo Bot
Zalo Bot là sản phẩm riêng, tách khỏi OA: tạo bot tại bot.zaloplatforms.com, lấy token, rồi nhận và gửi tin qua API của bot. Khách phải nhắn vào bot, nên bot hợp với tra cứu, thông báo nội bộ hay trợ lý cho đội. Chatbot trả lời khách của doanh nghiệp thường chạy trên OA hoặc trên Zalo cá nhân, xem chatbot Zalo cá nhân.
Zalo cá nhân: không có API chính thức, có MCP của ZaloDesk
Khách ở Việt Nam nhắn nhiều nhất vào Zalo cá nhân của nhân viên bán hàng, và đó là phần Zalo không mở API. ZaloDesk mở các tài khoản Zalo cá nhân và Zalo OA của công ty cho phần mềm qua máy chủ MCP (Model Context Protocol) tại https://app.zalodesk.com/api/mcp. Đăng nhập bằng tài khoản ZaloDesk, mỗi lệnh chạy đúng như người đó làm trên hộp thư web, nên Phân quyền áp dụng nguyên vẹn: nhân viên chỉ chạm được khách được giao.
Claude, Hermes và các AI agent hỗ trợ MCP liệt kê hội thoại, đọc tin, tìm khách theo số điện thoại, gắn nhãn, gửi trả lời và quản lý thành viên. Trong n8n, dùng node MCP Client với cùng địa chỉ. Từ dòng lệnh, chạy npx zalodesk login. Zalo cá nhân trả lời khi máy tính giữ tài khoản đó đang bật; Zalo OA trả lời từ hộp thư trên cloud. Với Zalo OA còn có API hỗ trợ khách hàng của ZaloDesk để giao hội thoại và xem nhật ký xử lý.
Câu hỏi thường gặp
Zalo có API không?
Có, cho Zalo OA và các dịch vụ doanh nghiệp: Official Account API (openapi.zalo.me), ZNS (business.openapi.zalo.me), Zalo Bot, đăng nhập bằng Zalo và Mini App. Zalo không có API chính thức cho tài khoản Zalo cá nhân.
Gói Zalo OA nào dùng được API?
Theo bảng giá của Zalo, tích hợp API có ở gói Tăng trưởng (100 yêu cầu/phút cho mỗi OA, 3 ứng dụng được cấp quyền) và Toàn diện (2.000 yêu cầu/phút, không giới hạn ứng dụng). OA phải được xác thực.
Access token Zalo OA hết hạn khi nào?
Access token sống 25 giờ. Refresh token sống 3 tháng, chỉ dùng được một lần và được thay mới mỗi lần làm mới; access token mới làm token cũ hết hiệu lực. Vì vậy chỉ một nơi trong hệ thống được làm mới token.
Webhook Zalo OA bị tắt vì sao?
Zalo chờ webhook trả 200 trong 2 giây. Lần gửi thất bại được thử lại sau 30 giây, 5, 15, 30 phút và 1 giờ; sau đó Zalo tắt webhook cho tới khi bạn đăng ký lại trong trang nhà phát triển.
Có API cho Zalo cá nhân không?
Zalo không có. ZaloDesk mở Zalo cá nhân và Zalo OA của công ty cho phần mềm qua máy chủ MCP tại app.zalodesk.com/api/mcp, đăng nhập bằng tài khoản ZaloDesk và chạy đúng Phân quyền của người đăng nhập. Zalo cá nhân trả lời khi máy tính giữ tài khoản đó đang bật; Zalo OA trả lời từ hộp thư trên cloud.
Nối Zalo với n8n thế nào?
Với Zalo OA: node HTTP Request gọi Official Account API, cộng một webhook trả 200 ngay rồi xử lý sau. Với Zalo cá nhân của công ty: node MCP Client trỏ tới máy chủ MCP của ZaloDesk để đọc hội thoại, tìm khách theo số điện thoại và gửi trả lời.
Nguồn tham khảo
- Zalo Platforms: tài liệu Official Account API : đọc 06/10/2026
- Zalo Platforms: tài liệu ZBS Template Message (ZNS) : đọc 06/10/2026
- Zalo Solutions: Bảng giá dịch vụ OA (hạn mức API theo gói) : đọc 09/11/2026
- Zalo Bot Platform