sender-profile-architect

Sender Profile の設計

Sender Profile は、テナントのアイデンティティ、チャネル設定、継承するリソース、請求、認証情報の運用上の境界です。境界の設定が不適切だと、ブランド、コンプライアンス方針、レート制限への影響、Webhook の所有権が混在する可能性がある場合は、プロビジョニングの前にこのスキルを使用してください。

本番環境で MCP プロファイルのライフサイクルを操作するには sent-profile-provisioning を、マーケット要件を確認するには sent-compliance を使用してください。MCP では、組織の権限付与に限り、通常のアカウントツールで任意の profileId を指定して操作対象のプロファイルを選択します。sender_profiles.* ツールは対象の id に対して操作し、操作対象の profileId は受け付けません。以下の REST ヘッダーは MCP の引数ではありません。

推奨されるテナントモデル

テナントに分離が必要な場合は、Sent の組織を 1 つ用意し、テナントごとに Sender Profile を 1 つ割り当てることを推奨してください。テナントが実際に同じブランド、送信者リソース、コンプライアンス方針、請求／レート制限の想定、運用上の影響範囲を共有している場合に限り、共有プロファイルが適切です。

デフォルトでプールするアーキテクチャは推奨しないでください。references/multi-tenancy-patterns.md を使って、分離の判断を明確にしてください。

認証パターン

Sent v3 は次の両方をサポートしています。

パターン	ヘッダー	影響範囲
プロファイル固有の API キー	x-api-key	プロファイルにスコープされた認証情報とレート制限コンテキストです。x-profile-id は追加しないでください。
子プロファイルに対して操作する組織 API キー	x-api-key と x-profile-id: <profile UUID>	組織の認証情報で、許可された子プロファイルにアクセスできます。レート制限は引き続き組織のプールが適用されます。

x-profile-id を送信できるのは組織キーのみです。プロファイルキーでこれを送信すると 403 が返されます。組織外のプロファイルを指定すると 404 が返されます。スコープされたレスポンスでは X-Profile-Id が返される場合があります。

x-sender-id はレガシーな v1/v2 の用語に限られます。v3 の認証やルーティングには使用しないでください。

テナント単位での認証情報の分離と失効を優先する場合は、プロファイルキーを選択してください。より広い範囲に及ぶ認証情報を保護し、組織内で共有されるレート制限プールを意図的に受け入れる、一元管理されたインテグレーションには、組織キーによるスコープ設定を選択してください。

プロファイルの作成モデル

POST /v3/profiles で作成します。name は必須です。現在、次の項目を任意で設定できます。

• アイデンティティ：icon、description、short_name；
• 共有：allow_contact_sharing、allow_template_sharing；
• 継承：inherit_contacts、inherit_templates、inherit_tcr_brand、inherit_tcr_campaign；
• 請求：billing_model、billing_contact、一時的な payment_details；
• 専用の WABA 認証情報：waba_id、任意の phone_number_id、access_token を含む whatsapp_business_account；
• 専用ブランド：brand.contact、brand.business、brand.compliance。

別個のブランドエンドポイントは追加しないでください。専用ブランドはプロファイルと同時に作成し、キャンペーンは /v3/profiles/{profileId}/campaigns で管理します。

継承ルール

• inherit_tcr_brand: true の場合、プロファイルは組織のブランドを使用し、独自の brand オブジェクトを送信できません。
• inherit_tcr_campaign: true の場合、継承したキャンペーンはそのプロファイルでは読み取り専用になります。
• 継承したブランドと inherit_tcr_campaign: false の組み合わせは、サポートされている専用キャンペーンのパターンです。
• 共有フラグはプロファイルの連絡先／テンプレートを公開し、継承フラグは組織のリソースを使用します。この 2 つの方向性は別々に扱ってください。

請求と番号参照

billing_model は現在、profile、organization、profile_and_organization をサポートしています。プロファイル単位またはフォールバックの請求モデルを使用する場合、請求先が未設定なら billing_contact が必要です。カード情報のフィールドは決済処理事業者に転送されるため、ログへの記録や永続化を行ってはなりません。

プロファイルの更新では、sending_phone_number_profile_id、sending_whatsapp_number_profile_id、sending_phone_number、whatsapp_phone_number、allow_number_change_during_onboarding を管理できます。モデル参照 ID と直接指定する番号は別々に扱い、あるプロファイルが別のプロファイルを参照する際に循環が生じないようにしてください。

WABA の選択肢

方法は大きく分けて 3 つあります。

1. ダッシュボードで組織の Embedded Signup を行います。
2. 組織に WABA がある場合、whatsapp_business_account を省略して子プロファイルに継承します。
3. waba_id と access_token を使って専用プロファイル WABA を設定します。phone_number_id は任意です。

組織の Embedded Signup を開始する公開エンドポイントはありません。POST /v3/profiles で直接認証情報を指定することは、「Embedded Signup エンドポイント」ではありません。運用フローには waba-embedded-signup を使用してください。

10DLC とキャンペーン

専用ブランドにはプロファイルの brand オブジェクトを使用します。キャンペーンは次のエンドポイントで管理します。

• GET|POST /v3/profiles/{profileId}/campaigns
• PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}

ペイロードとポリシーのレイヤーには sms-10dlc-registration を使用してください。

完了とステータスの処理

プロファイルを完了するには、必須の webHookUrl を指定して POST /v3/profiles/{profileId}/complete を実行します。

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

ステータスは、使用するインターフェースによって異なります。

• 作成レスポンスでは、現在、小文字の incomplete が示されています。
• 完了処理の 202 は処理開始を意味し、最終ステータスは含まれません。
• 完了処理の 200 では、完了済みのプロファイルに対して現在、小文字の completed が示されています。
• 完了コールバックでは、COMPLETED、SUBMITTED、または failed が報告されることがあります。
• REST ガイドと OpenAPI では、異なるプロファイルステータスの集合が公開されています。

REST の列挙値が固定されているとは見なさないでください。不明な文字列は保持し、その値を返したエンドポイントまたはコールバックのインターフェースを記録してください。

Webhook の帰属判定

送信イベントには、アプリケーションのテナント ID は含まれません。送信前に、返された message_id をテナントおよびプロファイルと関連付けて保存してください。送信ステータスイベントは、その対応付けを通じて振り分けます。受信メッセージについては、受信番号またはプロファイルリソースをテナントに対応付けてください。

message_id -> tenant_id, profile_id, logical_send_id, channel
receiving_number -> tenant_id, profile_id

account_id だけからテナントの所有者を推測しないでください。複数のテナントプロファイルが 1 つの組織に属する場合があります。

設計チェックリスト

• テナントとブランドの分離方針が明確です。
• 認証情報のパターンと、レート制限および影響範囲が文書化されています。
• 共有と継承の方向が意図どおりです。
• 課金の所有者が明示されています。
• 番号の参照が循環しないようになっています。
• WABA の経路は、組織のサインアップ、継承、専用認証情報のいずれかであり、想定外のハイブリッド方式ではありません。
• 専用ブランドとキャンペーンの経路はプロファイルベースです。
• message_id と受信番号の対応付けにより、Webhook の帰属判定が可能です。
• 不明なプロファイルステータスを許容します。
• テナントのオフボーディング時に、認証情報を無効化し、送信を停止し、リソースを安全に切り離し、監査証跡を保持します。

実装パターンについては、references/sender-profile-data-model.md と references/profile-boundary-examples.md を参照してください。