Zalo Official Account API vs Personal-Account Webhook: Which Inbound Path Fits?

If you need an official business presence and Zalo Official Account features, use the Zalo Official Account API. If your real requirement is to receive messages sent to an existing ordinary Zalo account and route them into your own support system, a signed personal-account webhook can be the more direct fit. The choice is primarily about which account identity customers already message, not which integration has the longest feature list.

Key takeaways

• Zalo describes an Official Account as the official account of a business and presents creation, verification, setup, engagement, and operation as the OA journey.
• The official developer path is explicitly an Official Account API path.
• UnifyPort connects an ordinary Zalo account with QR authorization and emits normalized inbound events through a webhook.
• Choose the official API for OA-native capabilities and an official platform relationship; choose the unofficial interface when preserving an existing ordinary-account inbox is the core requirement.
• Keep your receiver signed and store inbound events immediately, whichever downstream tools you add later.

Zalo Official Account API vs personal-account webhook

The two options start from different account models. Zalo’s Official Account site defines OA as an official business account and describes creating and verifying an OA as part of getting started. Zalo’s developer documentation names the corresponding developer surface the Official Account API.

A personal-account webhook takes a different starting point: an existing ordinary Zalo account is authorized, and messages observed on that account are delivered to your application as normalized webhook events. In UnifyPort, Zalo authorization is QR-only; no provider credentials are required before the scan, and the account identity is discovered through that scan.

Decision factor	Zalo Official Account API	Personal-account webhook through UnifyPort
Customer-facing identity	A Zalo Official Account	An existing ordinary Zalo account
Initial setup	Create and configure the OA developer path	Create a Zalo messaging account and scan a QR code
Inbound delivery	OA-specific API and webhook model	Normalized message.received events
Cross-channel handling	Build around Zalo’s model	Reuse the same event envelope for Zalo, WhatsApp, LINE, Telegram, TikTok, and X
Best fit	OA-native business workflows and official support	An inbound queue built around an ordinary account
Main trade-off	OA setup and account-model requirements	Session continuity and unofficial-interface risk must be managed

This is not a claim that one path is universally better. They solve adjacent but different jobs.

Choose the official OA path when identity and platform features come first

The official path is the stronger choice when the Zalo Official Account itself is part of the product requirement. Examples include a business that wants customers to find and interact with its OA, a team whose operating process depends on OA Manager, or an organization that requires an official vendor relationship for governance.

It is also the safer default when procurement, legal review, or platform-specific support requires official documentation and escalation. An unofficial interface should not be presented as a substitute for Zalo verification or for every OA-native product.

Before committing, write the requirement in one sentence: “Customers will message our Zalo Official Account, and our workflow depends on OA capabilities.” If that statement is accurate, evaluate the official API first.

Choose a personal-account webhook when the inbox already exists

The alternative becomes relevant when the requirement sounds different: “Customers already message this ordinary Zalo account, and our team needs those messages in Slack, a CRM, or an AI-assisted queue.” In that case, replacing the identity with a new OA may be more change than the workflow needs.

UnifyPort’s Zalo authorization guide documents a QR-only connection. The practical sequence is:

1. Register a webhook endpoint before authorization so authentication and inbound events have a destination.
2. Create a Zalo account with provider: zalo and auth_mode: qrcode.
3. Start the QR authorization flow and scan it with the intended Zalo account.
4. Wait for authentication success, then process message.received events where data.message.direction is inbound.
5. Verify each delivery with the configured signing_secret and HMAC-SHA256 contract before parsing or routing it.

For a wider architecture example, see how a single webhook can handle LINE, Zalo, and X. If you prefer a build-log workflow, the Claude Code Zalo webhook receiver tutorial shows how the same documentation can guide a small implementation.

Design the inbound layer before choosing downstream tools

The most durable decision is not “CRM or Slack?” It is the event contract between Zalo and those tools. Register a receiver that acknowledges valid deliveries quickly, stores the event, and then dispatches work asynchronously.

UnifyPort’s envelope includes id, type, provider, account_id, occurred_at, and event-specific data. For incoming messages, the documented data object contains conversation, sender, and message. Use the event ID for idempotent processing of ordinary event retries, but keep your own stored record because UnifyPort does not provide a REST message-history API or guaranteed replay.

The signature contract is also explicit: X-Device-Signature is the hexadecimal HMAC-SHA256 of the timestamp, a period, and the raw request body. Verify the raw bytes before JSON parsing. The webhook delivery documentation contains the complete header, acknowledgement, retry, and ordering rules.

Limitations and trade-offs

An ordinary-account connection depends on the continued validity of its authorized session. Your runbook should monitor authentication and runtime status, surface account.auth.required, and require a human to complete a new QR scan when needed. Platform behavior and availability can also vary by account or region.

The official OA route has a different operational cost: it is a separate business identity and developer model. That may be exactly what a brand needs, but it is not automatically the right answer for a team whose customers already use an ordinary account.

Do not run both paths merely because both exist. Pick the customer-facing identity first, list the platform features that are genuinely required, then choose the integration matching that list.

FAQ

Is the Zalo Official Account API for personal accounts?

The official developer surface is named the Official Account API and is centered on a Zalo Official Account. An ordinary account requires a different integration model.

Can an ordinary Zalo account receive messages through a webhook?

Yes, through UnifyPort’s unofficial interface. The account is connected by QR authorization, and incoming messages are normalized as message.received webhook events.

Do I need Zalo developer credentials for the UnifyPort QR flow?

No credentials are required up front for the documented Zalo flow. The user identity is discovered when the intended account scans the QR code.

Which option is better for a multi-channel support queue?

A normalized webhook is usually simpler when one receiver must handle Zalo alongside WhatsApp, LINE, Telegram, TikTok, or X. Use the official OA API instead when OA identity and OA-native features are requirements.

Is the unofficial interface the right choice for every team?

No. Choose the official route when verification, official support, governance, or OA-specific functions matter more than preserving an ordinary-account inbox.

Next step

Start with the Zalo authorization guide, then confirm the receiver’s signature handling in the webhook delivery reference before connecting Slack, a CRM, or an AI workflow.

Sources

Checked on 2026-08-23:

• Zalo Official Account
• Zalo for Developers: Official Account API