waba-embedded-signup

WABA オンボーディングと Embedded Signup

3 つの連携方法を明確に区別してください。すべてを「Embedded Signup」と呼ぶと、誤った API 設計や安全でない認証情報の取り扱いにつながります。

3 つの方法

方法	開始場所	プロファイルの動作
組織の Embedded Signup	Sent ダッシュボード	ホストされた Meta フローを通じて、組織の WABA を接続します。このフローを開始する Sent の公開エンドポイントはありません。
組織 WABA の継承	POST /v3/profiles	whatsapp_business_account を省略すると、子プロファイルは組織の接続済み WABA を継承します。
子プロファイル専用 WABA	POST /v3/profiles	whatsapp_business_account.waba_id と .access_token を指定します。phone_number_id は任意です。

認証情報を省略し、組織に接続済みの WABA がない場合、プロファイルの作成は 422 を返します。WABA 認証情報の直接指定はプロファイル作成の機能であり、公開の「Embedded Signup エンドポイント」ではありません。

認証

次のいずれかを使用してください。

• プロファイル固有のキーを x-api-key に指定する
• 組織キーを x-api-key に指定し、既存の子プロファイルに対して操作する場合は x-profile-id も指定する

x-profile-id を使用できるのは組織キーのみです。プロファイルキーでは 403 が返されます。x-sender-id は v1/v2 で使われていた旧用語です。

方法 A：組織の Embedded Signup

1. 認証された組織管理者が、Sent ダッシュボードの WhatsApp 接続フローを開きます。
2. ホストされた Meta Embedded Signup UI で、Meta の認証と WABA／電話番号の選択を行います。
3. 継承を使う子プロファイルを作成する前に、組織に接続済みの WABA が表示されていることを確認します。
4. 秘密情報ではない識別子を記録し、誰が操作を完了したかを監査できるようにします。

Sent の公開 API に POST /embedded-signup やトークン交換エンドポイントを作らないでください。Sent ダッシュボードの外部で独自の Meta Tech Provider 連携を構築する場合は、Meta の最新ドキュメントに従い、そのシステムを Sent API の仕様とは分離してください。

Meta のブラウザー postMessage イベントでは、event フィールドと、入れ子になったデータ／セッション情報を使用します。これらを Sent の webhook の sub_type エンベロープとして書き換えないでください。

方法 B：組織 WABA を継承する

whatsapp_business_account を省略します。

{
  "name": "Tenant Support",
  "description": "Synthetic child profile",
  "short_name": "SUPPORT",
  "inherit_templates": true,
  "billing_model": "organization",
  "sandbox": true
}

組織 WABA が接続された後にのみ使用してください。継承すると、テナントがその WABA の境界を共有します。これがテナント／ブランドのアーキテクチャに合致することを確認してください。

方法 C：専用 WABA の認証情報

{
  "name": "Dedicated Tenant",
  "whatsapp_business_account": {
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "access_token": "<injected secret>"
  },
  "sandbox": true
}

waba_id と access_token は必須です。phone_number_id は任意です。省略した場合、現在の仕様ではオンボーディング中にプロビジョニングと登録を行います。

トークンには、該当する WhatsApp Business のメッセージ送信権限と管理権限が必要です。シークレットマネージャーから注入してください。トークンをログに記録したり、出力に含めたり、フィクスチャに書き込んだり、ブラウザーに返したり、サポート用の出力に含めたり、一般的なプロファイルストレージに保持したりしないでください。Sent は API レスポンスでトークンを返しません。

プロファイルを完了する

必須の webHookUrl を指定して POST /v3/profiles/{profileId}/complete を呼び出します。

{
  "webHookUrl": "https://example.com/webhooks/profile-complete",
  "sandbox": true
}

• 202 はバックグラウンド処理が開始されたことを意味します。このレスポンスには最終ステータスはありません。
• 200 は、プロファイルがすでに完了していることを意味する場合があり、現在の仕様では小文字の completed が使われています。
• 完了コールバックでは、COMPLETED、SUBMITTED、または failed が報告されることがあります。

完了コールバックは独立した連携インターフェースとして扱ってください。そのエンベロープでは sub_type ではなく event が使用されます。

{
  "event": "COMPLETED",
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-08-09T12:00:00Z"
}

未知のイベント文字列はそのまま保持してください。Sent がコールバックエンドポイント向けに定める方法で真正性を検証し、処理を冪等にしてください。

運用準備状況の確認

• プロファイルの WABA ID が対象のビジネスと一致していることを確認します。
• 選択した番号が対象のプロファイルに割り当てられていることを確認します。
• テンプレートの共有／継承が意図したとおりであることを確認します。
• sandbox: true を指定してテスト用テンプレートを作成できることを確認します。
• 完了コールバックに到達でき、冪等性があることを確認します。
• Webhook 処理の前に、返されたメッセージ ID がテナント／プロファイルに関連付けて保存されることを確認します。
• トークンと支払い金額がログに含まれていないことを確認します。

通常のメッセージおよびテンプレートの Webhook については、Sent の最新のイベントリファレンスに従ってください。これらは、Meta のブラウザーイベントやプロファイル完了コールバックとは別のものです。

障害時の対応

障害	次の対応
認証情報を省略した場合の 422	組織の WABA を接続するか、専用の認証情報を指定します。
プロファイルキーと x-profile-id を指定した場合の 403	x-profile-id を削除するか、認証済みの組織キーを使用します。
WABA／番号が間違っている	完了処理の前に停止し、プロファイルの割り当てを修正します。
トークンの有効期限切れ／スコープ不足	安全に置き換えます。原因の調査中にトークンを表示してはいけません。
完了ステータスが submitted のまま	前提条件とコールバックの証跡を確認します。202 だけで最終的な失敗と判断してはいけません。

references/waba-embedded-signup-spec.md、references/waba-onboarding-runbook.md、および references/whatsapp-sender-profile-mapping.md を参照してください。テナント境界には sender-profile-architect を、最初のテンプレートには waba-template-author を使用してください。