WhatsApp Embedded Signup 完了後の検証チェックリスト
WhatsApp Embedded Signup の画面が完了しても、バックエンドのオンボーディングが完了したとは限りません。テナントを有効にする前に、完了イベントをサーバーセッションと照合し、token を検証し、対象 WABA を特定し、システムユーザー権限と電話番号の状態を確認し、WABA を購読したうえで、実際の webhook を1件通す必要があります。各確認を独立した受け入れ条件にしてください。
要点
FINISH_WHATSAPP_BUSINESS_APP_ONBOARDINGは Coexistence 画面の完了を示しますが、バックエンド全体の成功は示しません。- Meta の公式 Embedded Signup collection では、共有 WABA の取得、システムユーザーの管理、必要な電話番号登録、WABA webhook 購読が後続作業として示されています。
- 一覧の先頭 WABA を選ばず、現在のテナントと business asset に厳密に一致させます。
- credit line の接続は partner-paid モデルだけに必要で、共通の完了条件ではありません。
- 正しいテナントへ届いた実 webhook が検証、重複排除、応答まで通ることが運用上の完了条件です。
Embedded Signup 完了後に確認する項目
Meta の公式 Embedded Signup collectionは、ブラウザー上の完了と Graph API の後続処理を分けています。共有 WABA の取得、システムユーザーの追加または確認、電話番号登録、app の購読、必要な場合の credit line 共有が含まれます。
既存の Embedded Signup v4 移行チェックリストは起動設定と Coexistence の維持が対象です。本記事は完了イベント後から始まり、アプリに「接続済み」と表示するための証拠を定義します。
| ゲート | 保存する証拠 | 失敗時の境界 |
|---|---|---|
| セッション照合 | tenant ID、one-time state、configuration ID、時刻 | 別テナントへ誤接続する |
| Token 検証 | app、scope、有効期限 | token があっても WABA を管理できない |
| WABA 特定 | business と一致する WABA ID | 先頭要素が別顧客の場合がある |
| システムユーザー | system user と必要 task | 画面完了後の Graph API が失敗する |
| 電話番号 | phone-number ID と登録または Coexistence 状態 | asset はあるが messaging が使えない |
| App 購読 | subscribed_apps に対象 WABA | Meta には届くが webhook が来ない |
| 実配信 | event、tenant routing、検証、応答 | 設定だけで E2E 証拠がない |
順番に実装する
1. サーバーセッションと画面結果を照合する
Meta 画面を開く前に、サーバーで one-time state を発行し、tenant、操作ユーザー、configuration ID、オンボーディング経路を保存します。完了結果は一度だけ受理し、期限切れや不一致は拒否します。token をブラウザーログ、analytics、error report に残さないでください。
Coexistence では公式の FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING を記録します。別の Embedded Signup 経路は、その経路の現行公式 contract に従い、表示文言や単一の version 値だけで振り分けないようにします。
2. Asset ID より先に token を検証する
Meta の token debugging で token が自分の app に属し、必要な権限を持つことを確認します。token が空でないだけでは不十分です。監査と更新に必要な最小メタデータだけをサーバー側に保存し、token 本文はログへ出しません。
3. 対象 WABA を決定的に選ぶ
business がアクセスできる shared/client WABA を取得し、現在のセッション情報と正確な WABA ID を照合します。マルチテナントでは配列順に依存しません。一致しない場合は verification_required として復旧可能にし、別 asset を自動接続しないでください。
4. システムユーザーと電話番号経路を確認する
公式 collection の GET /{waba-id}/assigned_users で対象 system user と必要 task を確認します。標準 Cloud API では電話番号登録が必要な場合があります。Coexistence は WhatsApp Business app に接続済みの番号を使うため、再登録せず現行状態を確認します。この公式2画面モデルが必要かは Coexistence 判断ガイドで確認できます。
5. WABA を購読し、実配信を証明する
サーバー資格情報で POST /{waba-id}/subscribed_apps を呼び、その後に購読状態を再確認します。電話番号と購読は別々に成功・失敗し得るため、状態を分離します。
最後に制御されたテストメッセージを使い、実 webhook に tenant lookup、payload 検証、重複排除、acknowledgement を通します。UnifyPort の receiver では webhook 配信と署名検証に従い、raw body、X-Device-Timestamp、X-Device-Signature、endpoint の signing_secret を検証します。
UnifyPort が適合する範囲
UnifyPort は Meta Embedded Signup、WABA 権限付与、Cloud API 電話番号登録、credit line 接続、Coexistence 維持を行いません。それらが必要な Solution Partner や Tech Provider には公式フローが適切です。
UnifyPort は通常の WhatsApp アカウントを接続し、対応する受信メッセージを標準 message.received にする、より限定された経路です。顧客 WABA のプロビジョニングではなく受信キューが目的なら、WhatsApp 受信の3経路を比較し、WhatsApp 認証ガイドを確認してください。
制限とトレードオフ
このチェックリストは Meta の business eligibility、App Review、display name 承認、番号品質、policy compliance を証明しません。これらは別の platform state です。テストテナント成功も全顧客の成功を保証しません。
非公式インターフェースは Cloud API asset を付与できず、マルチテナント SaaS の Embedded Signup を代替できません。一方、画面完了も tenant mapping、retry、webhook receiver、billing boundary の正しさを証明しません。「画面完了」と「運用可能」を別状態にしてください。
FAQ
FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING は何を意味しますか？
WhatsApp Business app onboarding 画面が公式の完了状態になったことを示します。バックエンドではセッション、asset、権限、購読、実配信を引き続き検証します。
Embedded Signup token だけで接続済みにできますか？
できません。token と正確な WABA、system user、電話番号経路、webhook 購読を確認してください。
すべての連携で credit line が必要ですか？
いいえ。パートナーが Meta へ支払い、顧客へ請求するモデルにだけ対応手順が必要です。
Coexistence の番号は再登録しますか？
いいえ。公式状態と同期経路を確認し、標準電話番号登録を繰り返しません。
最後の受け入れ信号は何ですか？
少なくとも1件の制御された webhook が正しい tenant に届き、本番相当 receiver で検証・応答されることです。
次のステップ
Meta の公式 Embedded Signup collectionに沿ってゲートを実装してから tenant を有効化してください。通常アカウントの受信だけなら UnifyPort WhatsApp 認証を評価します。
情報源
公式情報の確認日：2026-08-05。