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 列入使用流程。開發者文件中的對應能力命名為 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 endpoint，讓授權及入站事件有接收位置。
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 是把時間戳、句點及原始 request body 串接後計算的十六進制 HMAC-SHA256。必須在解析 JSON 前驗證原始 bytes。完整確認、重試及排序規則請看 Webhook 傳送文件。

限制與取捨

一般帳戶連線依賴已授權的工作階段。營運手冊應監察授權及 runtime 狀態、處理 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