Zalo Official Account API 與個人帳號 Webhook：入站訊息該選哪一條路？

若你需要正式的企業身分與 Zalo Official Account（OA）功能，應優先評估 Zalo Official Account API。若客戶原本就在聯絡某個一般 Zalo 帳號，而你的目標只是把訊息送進客服系統、CRM 或 AI 工作流程，連接個人帳號的簽章 Webhook 通常更直接。關鍵不是哪一邊功能較多，而是客戶實際聯絡的是哪種帳號身分。

重點整理

• Zalo 將 Official Account 定義為企業在平台上的官方帳號，並把建立、驗證、設定與營運列入 OA 流程。
• 官方開發介面明確是 Official Account API。
• UnifyPort 透過 QR code 授權連接一般 Zalo 帳號，再以統一 Webhook 傳送入站事件。
• 需要 OA 原生功能、官方支援與治理時選官方 API；需要保留既有一般帳號收件匣時，可評估非官方介面。
• 不論後端接 Slack、CRM 或 AI，都要先完成簽章驗證與事件保存。

Zalo OA API 與個人帳號 Webhook 的差別

Zalo 的 Official Account 官網將 OA 描述為企業在 Zalo 平台上的官方帳號，並把建立與驗證 OA 列入使用旅程。Zalo 開發者文件中的對應介面也命名為 Official Account API。

個人帳號 Webhook 的起點不同：先授權一個既有的一般 Zalo 帳號，再把該帳號收到的訊息轉成標準事件交給應用程式。UnifyPort 的 Zalo 授權只支援 QR code；掃描前不必準備 Zalo 開發者憑證，帳號身分在掃描後確認。

決策面向	Zalo Official Account API	UnifyPort 個人帳號 Webhook
對客身分	Zalo Official Account	既有一般 Zalo 帳號
初始設定	建立並設定 OA 開發流程	建立 Zalo 訊息帳號並掃描 QR code
入站傳送	OA 專屬 API 與 Webhook 模型	統一 message.received 事件
多渠道擴充	依 Zalo 模型個別建置	Zalo、WhatsApp、LINE、Telegram、TikTok、X 共用事件結構
最適合	OA 原生業務與官方支援需求	以一般帳號為核心的入站佇列
主要取捨	OA 身分及設定要求	需管理工作階段連續性與非官方介面風險

這不是哪一條路全面勝出的比較，而是兩個相鄰、但不同的工作。

何時選擇官方 OA 路徑

如果 Zalo Official Account 本身就是需求，官方路徑較合理。例如企業希望顧客透過 OA 找到品牌、營運流程仰賴 OA Manager，或採購與法遵要求正式的平台關係與支援窗口。

先把需求寫成一句話：「顧客會聯絡我們的 Zalo Official Account，而且流程依賴 OA 功能。」若這句話成立，就先評估官方 API。非官方介面不應被當成 Zalo 驗證或所有 OA 原生產品的替代品。

何時選擇個人帳號 Webhook

另一類需求通常是：「顧客已經在傳訊息給這個一般 Zalo 帳號，我們要把內容送到 Slack、CRM 或統一客服佇列。」為了串接後台而更換顧客熟悉的帳號身分，可能會讓專案不必要地擴大。

UnifyPort 的 Zalo 授權指南記載以下流程：

1. 先註冊 Webhook 端點，讓授權與入站事件有接收位置。
2. 建立 provider: zalo、auth_mode: qrcode 的 Zalo 訊息帳號。
3. 啟動 QR code 授權，並由目標 Zalo 帳號掃描。
4. 授權完成後，處理 data.message.direction 為 inbound 的 message.received 事件。
5. 依設定的 signing_secret 與 HMAC-SHA256 規則驗證，再解析及路由訊息。

若要了解多渠道架構，可閱讀以一個 Webhook 處理 LINE、Zalo 與 X；偏好實作紀錄則可參考使用 Claude Code 建置 Zalo Webhook 接收器。

先設計入站層，再選下游工具

最需要穩定的不是「Slack 或 CRM」，而是 Zalo 與這些工具之間的事件契約。接收端應快速確認有效請求、保存事件，再以非同步方式分派工作。

UnifyPort 事件信封包含 id、type、provider、account_id、occurred_at 與依事件改變的 data。入站訊息的 data 包含 conversation、sender、message。一般事件重試可用事件 ID 做冪等處理，但仍要自行保存資料，因為系統沒有 REST 訊息歷史讀取 API，也不保證遺漏內容可以重送。

X-Device-Signature 是將時間戳記、句點及原始請求本文串接後計算的十六進位 HMAC-SHA256。必須在解析 JSON 前驗證原始位元組。完整的確認、重試與順序規則請見 Webhook 傳送文件。

限制與取捨

一般帳號連線依賴已授權的工作階段。維運手冊應監控授權與執行狀態、處理 account.auth.required，並在必要時請帳號持有人重新掃描 QR code。不同帳號或區域的上游可用性也可能不同。

官方 OA 路徑則使用獨立企業身分及開發模型。這可能正是品牌需要的能力，但對已透過一般帳號服務顧客的團隊，不一定是最短路徑。

先決定顧客看到的帳號身分，再列出真正必要的平台功能，最後才選整合方式。

常見問題

Zalo Official Account API 可以直接用於個人帳號嗎？

官方開發介面名為 Official Account API，核心對象是 Zalo Official Account。一般帳號需要不同的整合模型。

一般 Zalo 帳號可以透過 Webhook 接收訊息嗎？

可以透過 UnifyPort 的非官方介面連接。QR code 授權後，入站訊息會成為 message.received Webhook 事件。

UnifyPort 的 Zalo QR code 流程需要開發者憑證嗎？

文件中的流程在掃描前不需要 Zalo 開發者憑證；使用者身分由目標帳號掃描後確認。

多渠道客服佇列適合哪一種？

若同一接收端還要處理 WhatsApp、LINE、Telegram、TikTok 或 X，統一 Webhook 通常較容易維護。若 OA 身分與原生功能是必要條件，則選官方 API。

非官方介面適合所有團隊嗎？

不適合。當驗證、官方支援、治理或 OA 專屬功能較重要時，官方路徑更適當。

下一步

先依 Zalo 授權指南確認帳號連接方式，再依 Webhook 傳送文件完成簽章驗證，最後才串接 Slack、CRM 或 AI 工作流程。

第一手來源

核對日期：2026-08-23。

• Zalo Official Account
• Zalo for Developers：Official Account API