What is Zalo OA integration and what do you need?
Zalo OA integration connects a business's Zalo Official Account to internal systems (CRM, ERP, sales software, chatbots) through the OA OpenAPI: your system calls APIs to send messages and manage the OA, and Zalo sends events (incoming messages, new followers and so on) to your webhook. To add an AI agent, place it behind a controlled integration layer rather than wiring it straight to the webhook.
According to Zalo OA documentation, operating through the OA OpenAPI requires three accounts: a Zalo Official Account, an App (Zalo App) authorised to manage the OA, and a ZBS Account that manages spending on paid services. Zalo also notes that the administrators of the OA, the App and the ZBS Account are personal Zalo users and need not be the same person. The documentation states Zalo does not charge for integration, though businesses may need to pay for OA packages and some features; this guide does not cover pricing, so check Zalo's official price list.
Note: Zalo's policies change fairly often. Every rule below is taken from official documentation at the time of writing (October 2026); before you build, check Zalo's current rules.
OA OpenAPI vs ZBS Template Message (ZNS) vs Mini App
These three are often confused. According to Zalo OA's guide, from 1 January 2026 ZBS Template Message is the solution that merges UID transactional messages, UID promotional messages and ZNS messages; many technical documents still use the ZNS name for the API.
- For two-way customer care: start with consultation messages and webhooks.
- For order confirmations, appointments and payment reminders: use ZBS Template Message with approved templates.
- For flows needing forms, date pickers or payment: consider a Mini App.
| Channel | Used for | Main conditions (per Zalo docs) | Fit for an AI agent |
|---|---|---|---|
| Consultation messages via OA OpenAPI | Replying to and advising customers who ask | User has interacted with the OA and has not blocked it; via OpenAPI, sendable within 7 days of the last interaction | Main channel for a support agent, with human review where needed |
| Broadcast messages | General updates to followers | User follows the OA; sent from OA Manager between 06:00 and 19:59 | Do not let an agent send these; use it only to draft content |
| ZBS Template Message (formerly ZNS) | Template-based Transaction and After-sales messages sent by UID or phone number | Templates must be registered and approved by Zalo before sending | Agent fills parameters into approved templates, no free-form content |
| Zalo Mini App | Apps running inside Zalo that can request permission to notify | Per Mini App docs: notifications via the Mini App's shared OA, ZNS or UID messages | UI for multi-step flows (booking, forms) |
Architecture: Zalo OA with CRM and an AI agent
The recommended architecture flows one way: Zalo → webhook → integration layer → CRM → AI agent → human handover. Each layer has one responsibility, so when one part fails the rest stays safe.
1. Webhook receives events
Per the OA OpenAPI documentation, when an interaction event occurs between a user and the OA, Zalo sends an HTTP POST request to the app's webhook URL, for example when a user sends a message to the OA. The webhook endpoint should do only three things: verify the signature, put the event on a queue, and return success quickly. Do not call the AI model or CRM inside the webhook request.
2. Integration layer
This holds the logic: de-duplication, mapping Zalo UIDs to CRM customers, access-token management, send-message API calls and logging. Separating it lets you change CRM or AI model without touching the webhook receiver. See also why to integrate CRM/ERP before AI.
3. CRM as the source of truth
Conversations, consent status and order history belong in the CRM. The AI agent reads context from the CRM under granted permissions and does not keep its own copy of customer data.
4. AI agent and human handover
The agent classifies intent, drafts replies and looks up order status. For money questions, complaints, sensitive data or low confidence, it hands over to staff with a summary. Staff can reply in OA Manager while data stays centralised in the CRM, matching the model Zalo describes for businesses integrating several OAs with a CRM. For review checkpoints see human-in-the-loop and chatbot vs AI agent for customer service.
Webhooks: signatures, retries and idempotency
The webhook is your only entry point from outside, so treat it carefully.
- Verify the signature: Zalo webhook requests carry an X-ZEvent-Signature header; according to a Zalo support answer on the developers site, the value is mac = sha256 of the appId, event data, timestamp and OA secret key. Confirm the exact formula in the current webhook docs before coding, and reject requests with a bad signature.
- Respond fast: enqueue the event and return HTTP 200 immediately; run heavy work asynchronously.
- Idempotency: store a unique key per event (for example message ID plus event type and timestamp) and skip events already processed. This keeps you safe when the same event arrives more than once, for instance on redelivery or when several apps are authorised by the same OA.
- Retries on your side: when a send call fails for a transient reason, retry with increasing back-off and a cap; for business errors (sending window expired, template not approved) do not retry, hand over to a person.
- Dead-letter queue: events that fail repeatedly go to a separate queue for review instead of being lost.
- Structured logs: time received, signature result, idempotency key, action taken, who approved.
Managing access tokens and refresh tokens
According to the OAuth v4 page on the Zalo Platform Document Hub, an OA access token is valid for 25 hours (expires_in = 90000 seconds), a refresh token is valid for 3 months, and each refresh token can be used only once: a successful refresh returns a new access token and refresh token pair and invalidates the old refresh token. Because Zalo may change these values, always read expires_in from the API response instead of hard-coding lifetimes.
For the User Refresh Token (Social API, different from OA tokens), Zalo's official notice states a maximum lifetime of 30 days and that a new refresh token inherits the remaining lifetime of the token used to create it. This shows token rules can differ between APIs.
- Allow only one process to refresh tokens per App–OA pair; use a distributed lock across servers so two places do not refresh at once and invalidate each other.
- Persist the new token pair atomically as soon as you receive it; if the write fails you can lose the refresh token and have to re-authorise.
- Refresh proactively before expiry and alert on refresh failures.
- Keep tokens and secret keys in a secret manager, never in source code or logs.
User consent and personal data
An OA's right to message is tied to user interaction. Zalo's documentation lists recognised interactions such as sending a message to the OA, calling, commenting on posts, interacting with the chatbot, tapping the menu and following the OA. Consultation messages can only be sent when the user has interacted and has not blocked the OA. Zalo also warns that OAs must use each message type for its intended purpose, and that the system automatically restricts sending flows that show signs of bothering users.
Beyond Zalo's rules, storing phone numbers and conversation content and feeding them to an AI agent is personal-data processing. Define purposes, store consent evidence in the CRM, let users withdraw consent, and minimise what you send to the AI model. See Vietnam's Personal Data Protection Law 2025: a checklist for AI and SaaS systems.
- Record consent per purpose (consultation, transaction, after-sales) and its source.
- Do not send promotional content through transactional channels.
- Mask or trim sensitive data before it goes into a prompt.
- If unsure whether a message flow is allowed: check Zalo's current rules.
SDKs and tooling: official and unofficial
Zalo's developer documentation provides SDKs for several platforms, including Java, PHP and .NET (Dotnet SDK). Whichever SDK you use, check it against the official API documentation, since SDKs can lag behind changes on Zalo's side.
Zalo also lets you create a technical test OA account to develop and test before connecting a live OA.
If your team works in C#/.NET, calling the Zalo API from C#/.NET walks through OAuth, webhooks and OA messaging at code level.
Zalo OA integration checklist
Use the table below as a go-live checklist. If you want a team alongside you, EYC's integration and consulting service can help design the integration layer, the CRM and the AI agent handover points.
| Area | What to do | Done when |
|---|---|---|
| Accounts | OA, authorised Zalo App, linked ZBS Account | Admins of each account are recorded |
| Test environment | Use a technical test OA | End-to-end flow works on the test OA |
| Webhook | Verify signature, enqueue, return 200 fast | Bad-signature requests are rejected and logged |
| Idempotency | Unique key per event | Replaying an event creates no duplicates |
| Tokens | Single refresher, atomic save, failure alerts | Simulated expiry recovers automatically |
| Message types | Each flow mapped to the right type and conditions | No promotional flow uses a transactional channel |
| Templates | ZBS Template Message templates approved first | Agent only fills parameters into approved templates |
| CRM | Map UID to customer, store consent | History and consent status visible per customer |
| AI agent | Handover rules, limited permissions | Sensitive cases always reach staff with a summary |
| Monitoring | Logs, alerts, dead-letter queue | Someone owns alert handling |
Frequently asked questions
Does Zalo OA integration cost money?
According to Zalo OA documentation, Zalo does not charge for integration, but businesses may need to pay for OA packages and some features or message types. Check Zalo's official price list when you implement.
What is the difference between ZNS and ZBS Template Message?
According to Zalo OA's guide, from 1 January 2026 ZBS Template Message merges UID transactional messages, UID promotional messages and ZNS, with two main types: Transaction and After-sales messages. Some API documents still use the ZNS name.
Can an AI agent reply to customers on Zalo OA by itself?
Technically yes, through consultation messages once the user has interacted with the OA. It is wiser to limit the agent to low-risk questions, hand sensitive cases to staff and keep full logs.
Why do Zalo refresh tokens keep expiring?
It usually happens when tokens are refreshed in several places at once or the new refresh token is not saved, because each refresh token can be used only once. Per Zalo's documentation, refresh tokens last 3 months and access tokens 25 hours. Let a single process refresh and store the new pair immediately.
How long after an interaction can the OA OpenAPI send consultation messages?
According to Zalo OA documentation effective from 1 January 2026, the OA OpenAPI can send consultation messages within 7 days of the last interaction, while OA Manager allows 365 days. Check Zalo's current rules, as policies can change.