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では一般のZaloアカウントをQRコードで認証し、受信内容を統一Webhookイベントとして配信できます。
• OA固有機能、公式サポート、ガバナンスが必要なら公式API、既存の一般アカウント受信箱を維持したいなら非公式インターフェースを検討します。
• Slack、CRM、AIのどれへ接続する場合も、まず署名検証とイベント保存を実装します。

Zalo OA APIと個人アカウントWebhookの違い

ZaloのOfficial Account公式サイトは、OAを企業の公式アカウントとして説明し、OAの作成と認証を導入プロセスに含めています。開発者向けの対応する機能もOfficial Account APIという名称です。

個人アカウントWebhookは出発点が異なります。すでに利用中の一般Zaloアカウントを認証し、そのアカウントで観測したメッセージを標準イベントに変換してアプリケーションへ届けます。UnifyPortのZalo認証はQRコード方式のみで、スキャン前にZalo開発者資格情報を用意する必要はありません。アカウントIDはスキャンによって特定されます。

判断項目	Zalo Official Account API	UnifyPortの個人アカウントWebhook
顧客から見えるID	Zalo Official Account	既存の一般Zaloアカウント
初期設定	OAの作成と開発設定	Zaloメッセージングアカウントを作成しQRコードをスキャン
受信方式	OA固有のAPIとWebhookモデル	統一されたmessage.receivedイベント
複数チャネル	Zaloモデルに合わせて実装	Zalo、WhatsApp、LINE、Telegram、TikTok、Xで同じイベント構造
向いている用途	OAネイティブの業務、公式支援が必要な運用	一般アカウントを起点にした受信キュー
主な注意点	OAのID・設定要件	セッション継続性と非公式インターフェースのリスク管理

どちらかが常に優れているわけではなく、対象とする仕事が異なります。

公式OAを選ぶべきケース

Zalo Official Accountそのものが要件なら、公式ルートが適しています。たとえば、顧客がOAを通じて企業を見つける必要がある、運用がOA Managerに依存する、調達や法務が公式なプラットフォーム関係とサポート窓口を求める、といった場合です。

要件を「顧客は当社のZalo Official Accountへ連絡し、業務フローはOA機能に依存する」と一文で書けるなら、まず公式APIを評価してください。非公式インターフェースは、Zaloの認証制度やすべてのOA固有製品の代替ではありません。

個人アカウントWebhookが合うケース

別の典型的な要件は、「顧客はすでにこの一般Zaloアカウントへ連絡している。そのメッセージをSlack、CRM、共通サポートキューに入れたい」です。この場合、バックエンド連携のためだけに顧客が覚えているIDを変更すると、プロジェクト範囲が不必要に広がります。

UnifyPortのZalo認証ガイドに沿った流れは次のとおりです。

1. 認証イベントと受信イベントの送信先として、先にWebhookエンドポイントを登録します。
2. provider: zalo、auth_mode: qrcodeでZaloメッセージングアカウントを作成します。
3. QR認証を開始し、接続対象のZaloアカウントでスキャンします。
4. 認証完了後、data.message.directionがinboundのmessage.receivedイベントを処理します。
5. 設定したsigning_secretとHMAC-SHA256契約で検証してから、解析とルーティングを行います。

複数チャネルの考え方は、LINE・Zalo・Xを1つのWebhookで扱う構成が参考になります。日本のチームではLINEが中心になりやすいので、Zaloを追加しても同じ受信ハンドラーを維持できる点が重要です。実装の進め方は、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で計算した16進値です。JSON解析前のバイト列で検証します。確認応答、再試行、順序のルールはWebhook配信ドキュメントにまとまっています。

制限とトレードオフ

一般アカウント接続は認証済みセッションの有効性に依存します。運用手順では認証状態とランタイム状態を監視し、account.auth.requiredを検知したら、必要に応じてアカウント所有者にQRコードを再スキャンしてもらいます。上流の利用可否はアカウントや地域によって異なる場合もあります。

公式OAは別の企業IDと開発モデルを使います。ブランドには必要な構成でも、既存の一般アカウントで顧客対応しているチームにとって最短とは限りません。

まず顧客から見えるIDを決め、必要なプラットフォーム機能だけを列挙し、その条件に合う連携を選びましょう。

よくある質問

Zalo Official Account APIは個人アカウントに使えますか？

公式の開発者向け機能はOfficial Account APIであり、中心となる対象はZalo Official Accountです。一般アカウントには別の連携モデルが必要です。

一般Zaloアカウントの受信をWebhookへ送れますか？

UnifyPortの非公式インターフェースで接続できます。QR認証後、受信メッセージはmessage.receivedイベントとして配信されます。

UnifyPortのZalo QR認証に開発者資格情報は必要ですか？

ドキュメント上のフローでは事前の資格情報は不要です。対象アカウントがQRコードをスキャンするとユーザーIDが特定されます。

複数チャネルのサポートキューにはどちらが適していますか？

Zaloに加えてLINE、WhatsApp、Telegram、TikTok、Xを同じ受信サーバーで扱うなら、統一Webhookが管理しやすい構成です。OAのIDや固有機能が必須なら公式APIを選びます。

非公式インターフェースはすべてのチームに適していますか？

いいえ。認証、公式支援、ガバナンス、OA固有機能を優先する場合は公式ルートが適しています。

次のステップ

まずZalo認証ガイドで接続方式を確認し、Webhook配信ドキュメントに従って署名検証を完成させてから、Slack、CRM、AIワークフローへ接続してください。

一次情報

確認日：2026-08-23

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