Tích hợp Zalo OA là gì và cần những gì?
Tích hợp Zalo OA là kết nối tài khoản Zalo Official Account của doanh nghiệp với hệ thống nội bộ (CRM, ERP, phần mềm bán hàng, chatbot) qua bộ OA OpenAPI: hệ thống của bạn gọi API để gửi tin và quản lý OA, còn Zalo gửi sự kiện (tin nhắn đến, người dùng quan tâm…) về webhook của bạn. Muốn đưa AI Agent vào, bạn đặt agent phía sau một lớp tích hợp có kiểm soát, không gắn thẳng vào webhook.
Theo tài liệu Zalo OA, để vận hành bằng OA OpenAPI doanh nghiệp cần ba tài khoản: Zalo Official Account, một Ứng dụng (Zalo App) được cấp quyền quản lý OA, và tài khoản ZBS Account để quản lý chi tiêu cho các dịch vụ tính phí. Zalo cũng ghi rõ quản trị viên của OA, App và ZBS Account là người dùng Zalo cá nhân và không nhất thiết là cùng một người. Tài liệu nêu Zalo không tính phí tích hợp, nhưng doanh nghiệp có thể phải trả phí gói OA và một số tính năng; bài viết này không bàn về giá, hãy xem bảng giá chính thức của Zalo.
Lưu ý: chính sách của Zalo thay đổi khá thường xuyên. Các quy định dưới đây trích từ tài liệu chính thức tại thời điểm viết (10/2026); hãy kiểm tra lại quy định hiện hành trước khi triển khai.
OA OpenAPI, ZBS Template Message (ZNS) và Mini App khác nhau thế nào?
Ba nhóm công cụ này hay bị nhầm. Từ ngày 01/01/2026, theo trang hướng dẫn của Zalo OA, ZBS Template Message là giải pháp hợp nhất các loại tin UID Giao dịch, tin UID Truyền thông và tin ZNS; nhiều tài liệu kỹ thuật vẫn dùng tên ZNS cho phần API.
- Nếu mục tiêu là chăm sóc khách hàng hai chiều: bắt đầu với Tin Tư vấn và webhook.
- Nếu cần gửi xác nhận đơn hàng, lịch hẹn, nhắc thanh toán: dùng ZBS Template Message với mẫu đã duyệt.
- Nếu quy trình cần form, chọn ngày giờ, thanh toán: cân nhắc Mini App.
| Kênh | Dùng để làm gì | Điều kiện chính (theo tài liệu Zalo) | Phù hợp với AI Agent |
|---|---|---|---|
| Tin Tư vấn qua OA OpenAPI | Trả lời, tư vấn khi khách hỏi | Người dùng đã tương tác với OA và không chặn OA; qua OpenAPI gửi được trong 07 ngày kể từ tương tác cuối | Kênh chính cho agent hỗ trợ khách hàng, có người duyệt khi cần |
| Tin Broadcast | Cập nhật thông tin chung tới người quan tâm | Người dùng đang quan tâm OA; gửi trên OA Manager trong khung 6h00–19h59 | Không nên để agent tự gửi; chỉ hỗ trợ soạn nội dung |
| ZBS Template Message (trước là ZNS) | Tin Giao dịch và Tin Hậu mãi theo mẫu, gửi qua UID hoặc số điện thoại | Mẫu (template) phải được đăng ký và Zalo kiểm duyệt trước khi gửi | Agent điền tham số vào mẫu đã duyệt, không tự sinh nội dung tự do |
| Zalo Mini App | Ứng dụng chạy trong Zalo, có thể xin quyền gửi thông báo | Theo tài liệu Mini App: gửi thông báo qua OA chung của Mini App, ZNS hoặc tin UID | Giao diện cho quy trình có nhiều bước (đặt lịch, form) |
Kiến trúc tích hợp Zalo OA với CRM và AI Agent
Kiến trúc được khuyến nghị đi theo một chiều rõ ràng: Zalo → webhook → lớp tích hợp → CRM → AI Agent → bàn giao cho người. Mỗi lớp có một trách nhiệm riêng để khi một phần lỗi, phần còn lại vẫn an toàn.
1. Webhook nhận sự kiện
Theo tài liệu OA OpenAPI, khi có sự kiện tương tác giữa người dùng và OA, Zalo gửi request HTTP (POST) tới webhook URL của ứng dụng; ví dụ khi người dùng gửi tin nhắn đến OA. Endpoint webhook chỉ nên làm ba việc: xác thực chữ ký, ghi sự kiện vào hàng đợi, trả phản hồi thành công thật nhanh. Không gọi mô hình AI hay CRM trực tiếp trong request webhook.
2. Lớp tích hợp (integration layer)
Đây là nơi chứa logic: chống trùng lặp, ánh xạ UID Zalo với khách hàng trong CRM, quản lý access token, gọi API gửi tin, ghi log. Tách lớp này giúp bạn đổi CRM hoặc mô hình AI mà không phải sửa phần nhận webhook. Xem thêm vì sao nên tích hợp CRM/ERP trước khi làm AI.
3. CRM là nguồn dữ liệu chuẩn
Hội thoại, trạng thái đồng ý, lịch sử đơn hàng nên được lưu trong CRM. AI Agent đọc ngữ cảnh từ CRM theo quyền được cấp, không tự giữ bản sao dữ liệu khách hàng riêng.
4. AI Agent và bàn giao cho người
Agent phân loại ý định, soạn câu trả lời, tra cứu trạng thái đơn. Với câu hỏi về tiền, khiếu nại, dữ liệu nhạy cảm hoặc khi độ tin cậy thấp, agent chuyển cho nhân viên kèm tóm tắt. Nhân viên có thể trả lời trên OA Manager trong khi dữ liệu vẫn tập trung ở CRM, đúng mô hình Zalo mô tả cho doanh nghiệp tích hợp nhiều OA với CRM. Thiết kế điểm duyệt xem con người trong vòng lặp và chatbot hay AI Agent cho chăm sóc khách hàng.
Webhook: xác thực, retry và idempotency
Webhook là cửa ngõ duy nhất nhận dữ liệu từ bên ngoài, nên cần được xử lý cẩn thận.
- Xác thực chữ ký: request webhook của Zalo có header X-ZEvent-Signature; theo trả lời của đội hỗ trợ Zalo trên trang developers, giá trị là mac = sha256 của appId, dữ liệu sự kiện, timestamp và OA secret key. Kiểm tra công thức chính xác trong tài liệu webhook hiện hành trước khi lập trình, và từ chối request sai chữ ký.
- Phản hồi nhanh: ghi sự kiện vào hàng đợi rồi trả HTTP 200 ngay; xử lý nặng chạy bất đồng bộ.
- Idempotency: lưu khóa duy nhất của mỗi sự kiện (ví dụ mã tin nhắn kết hợp loại sự kiện và timestamp) và bỏ qua sự kiện đã xử lý. Thiết kế như vậy để an toàn khi cùng một sự kiện đến nhiều lần, ví dụ do gửi lại hoặc do nhiều ứng dụng cùng được OA ủy quyền.
- Retry phía bạn: khi gọi API gửi tin thất bại do lỗi tạm thời, thử lại với khoảng chờ tăng dần và giới hạn số lần; với lỗi nghiệp vụ (hết hạn điều kiện gửi, mẫu chưa duyệt) thì không thử lại mà chuyển cho người.
- Dead-letter queue: sự kiện xử lý lỗi nhiều lần được đưa vào hàng riêng để kiểm tra, không bị mất.
- Ghi log có cấu trúc: thời điểm nhận, kết quả xác thực, khóa idempotency, hành động đã thực hiện, ai duyệt.
Quản lý access token và refresh token
Theo tài liệu OAuth v4 trên Zalo Platform Document Hub, access token của OA có hiệu lực 25 giờ (expires_in = 90000 giây), refresh token có hiệu lực 3 tháng và mỗi refresh token chỉ dùng được một lần: khi refresh thành công, bạn nhận một cặp access token và refresh token mới, còn refresh token cũ hết hiệu lực. Vì Zalo có thể thay đổi các giá trị này, hãy luôn đọc expires_in trong phản hồi API thay vì hard-code thời hạn.
Với User Refresh Token (Social API, khác với OA token), thông báo chính thức của Zalo cho biết thời hạn tối đa 30 ngày và refresh token mới kế thừa thời hạn còn lại của token dùng để tạo ra nó. Đây là ví dụ cho thấy quy tắc token có thể khác nhau giữa các API.
- Chỉ một tiến trình được phép làm mới token cho mỗi cặp App–OA; dùng khóa phân tán nếu có nhiều máy chủ, tránh hai nơi cùng làm mới khiến token của nhau mất hiệu lực.
- Lưu cặp token mới một cách nguyên tử (atomic) ngay khi nhận; nếu ghi lỗi, bạn có thể mất refresh token và phải xin cấp quyền lại.
- Làm mới chủ động trước khi hết hạn và có cảnh báo khi làm mới thất bại.
- Lưu token và secret key trong kho bí mật (secret manager), không để trong mã nguồn hay log.
Đồng ý của người dùng và dữ liệu cá nhân
Quyền gửi tin của OA gắn với tương tác của người dùng. Tài liệu Zalo liệt kê các tương tác được công nhận như gửi tin nhắn đến OA, gọi thoại, bình luận bài viết, tương tác với chatbot, nhấn menu, quan tâm OA… Tin Tư vấn chỉ gửi được khi người dùng đã tương tác và không chặn OA. Zalo cũng cảnh báo OA phải dùng đúng loại tin cho đúng mục đích, và hệ thống có cơ chế tự động hạn chế các luồng gửi tin có dấu hiệu làm phiền người dùng.
Bên cạnh quy định của Zalo, việc lưu số điện thoại, nội dung hội thoại và đưa chúng vào AI Agent là xử lý dữ liệu cá nhân. Hãy xác định mục đích, lưu bằng chứng đồng ý trong CRM, cho phép người dùng rút lại đồng ý, và hạn chế dữ liệu gửi tới mô hình AI. Xem Luật Bảo vệ dữ liệu cá nhân 2025: checklist cho hệ thống AI và SaaS.
- Ghi trạng thái đồng ý theo từng mục đích (tư vấn, giao dịch, hậu mãi) và nguồn đồng ý.
- Không gửi tin truyền thông qua kênh dành cho giao dịch.
- Che hoặc lược bớt dữ liệu nhạy cảm trước khi đưa vào prompt.
- Nếu chưa chắc một luồng tin có được phép hay không: kiểm tra quy định hiện hành của Zalo.
SDK và công cụ: chính thức và không chính thức
Trang tài liệu nhà phát triển của Zalo cung cấp SDK cho nhiều nền tảng, trong đó có Java, PHP và .NET (Dotnet SDK). Dù dùng SDK nào, hãy đối chiếu với tài liệu API chính thức, vì SDK có thể chậm hơn so với thay đổi phía Zalo.
Zalo cũng cho phép tạo tài khoản OA thử nghiệm kỹ thuật để phát triển và kiểm thử trước khi kết nối OA thật.
Nếu đội ngũ của bạn dùng C#/.NET, bài gọi Zalo API từ C#/.NET hướng dẫn chi tiết OAuth, webhook và gửi tin OA ở mức mã nguồn.
Checklist triển khai tích hợp Zalo OA
Dùng bảng dưới đây làm danh sách kiểm tra trước khi đưa tích hợp vào vận hành. Nếu cần một đội làm cùng, dịch vụ tích hợp và tư vấn của EYC có thể hỗ trợ thiết kế lớp tích hợp, CRM và điểm bàn giao cho AI Agent.
| Hạng mục | Việc cần làm | Đã xong khi |
|---|---|---|
| Tài khoản | Có OA, Zalo App được cấp quyền, ZBS Account đã liên kết | Quản trị viên từng tài khoản được ghi nhận |
| Môi trường thử | Dùng OA thử nghiệm kỹ thuật | Luồng end-to-end chạy được trên OA thử |
| Webhook | Xác thực chữ ký, đưa vào hàng đợi, trả 200 nhanh | Request sai chữ ký bị từ chối và có log |
| Idempotency | Khóa duy nhất cho mỗi sự kiện | Gửi lặp một sự kiện không tạo bản ghi trùng |
| Token | Một tiến trình làm mới, lưu nguyên tử, cảnh báo lỗi | Mô phỏng token hết hạn mà hệ thống tự phục hồi |
| Loại tin | Mỗi luồng gắn đúng loại tin và điều kiện gửi | Không có luồng truyền thông qua kênh giao dịch |
| Template | Mẫu ZBS Template Message được duyệt trước | Agent chỉ điền tham số vào mẫu đã duyệt |
| CRM | Ánh xạ UID với khách hàng, lưu đồng ý | Tra được lịch sử và trạng thái đồng ý theo khách |
| AI Agent | Quy tắc chuyển cho người, giới hạn quyền | Ca nhạy cảm luôn tới nhân viên kèm tóm tắt |
| Giám sát | Log, cảnh báo, dead-letter queue | Có người phụ trách xử lý cảnh báo |
Câu hỏi thường gặp
Tích hợp Zalo OA có mất phí không?
Theo tài liệu Zalo OA, Zalo không tính phí tích hợp, nhưng doanh nghiệp có thể phải trả phí gói OA và một số tính năng hoặc loại tin. Hãy xem bảng giá chính thức của Zalo tại thời điểm triển khai.
ZNS và ZBS Template Message khác nhau thế nào?
Theo trang hướng dẫn Zalo OA, từ 01/01/2026 ZBS Template Message là giải pháp hợp nhất tin UID Giao dịch, tin UID Truyền thông và tin ZNS, gồm hai loại chính là Tin Giao dịch và Tin Hậu mãi. Một số tài liệu API vẫn dùng tên ZNS.
Có dùng AI Agent tự trả lời khách trên Zalo OA được không?
Về kỹ thuật có, thông qua Tin Tư vấn khi người dùng đã tương tác với OA. Tuy nhiên nên giới hạn agent ở các câu hỏi rủi ro thấp, chuyển cho nhân viên các ca nhạy cảm và ghi log đầy đủ.
Vì sao refresh token Zalo hay bị lỗi hết hạn?
Nguyên nhân thường gặp là làm mới token ở nhiều nơi cùng lúc hoặc không lưu được refresh token mới, vì mỗi refresh token chỉ dùng được một lần. Theo tài liệu Zalo, refresh token có hiệu lực 3 tháng và access token 25 giờ. Hãy chỉ cho một tiến trình làm mới và lưu cặp token mới ngay khi nhận.
Sau khi khách tương tác, OA gửi Tin Tư vấn qua API được trong bao lâu?
Theo tài liệu Zalo OA áp dụng từ 01/01/2026, OA OpenAPI gửi được Tin Tư vấn trong vòng 07 ngày kể từ tương tác cuối, còn OA Manager là 365 ngày. Hãy kiểm tra quy định hiện hành của Zalo vì chính sách có thể thay đổi.