sent-profile-provisioning

送信プロファイルのプロビジョニング

このスキルは、プロファイルのアーキテクチャ設計を実行に移すものです。テナンシーの境界を決定したら、API 呼び出し、完了コールバック、キャンペーン登録、ユーザー管理を実行し、プロファイルから送信できるようにします。まず sender-profile-architect で境界を設計し、ここでプロビジョニングしてください。

稼働中の MCP プロファイル操作

クライアントが管理する OAuth 2.1/PKCE を通じて、sender_profiles.list、sender_profiles.get、sender_profiles.create、sender_profiles.update、sender_profiles.delete を使用します。認証情報を要求または公開してはいけません。変更を行う前に account.get で呼び出し元の組織を検証してください。

これらのツールは、認証済みの組織のもとで動作します。対象の引数は profileId ではなく id です。sender_profiles.* ツールはいずれも、操作主体を指定する profileId を受け付けません。プロファイルへの権限付与は子プロファイルを所有せず、空のリストを受け取ります。組織のプロファイルを管理するには、組織スコープで再認証してください。

• 一覧／取得： 一覧取得では page（1 から始まる）と pageSize（1～100、デフォルトは 20）を使用し、チャネルの準備状況が返されます。その一覧にある実際の ID を使用してください。取得では found／item が返されます。found: false では、存在しない、削除済み、別の組織に属している、のいずれかを区別できません。他のテナントに属するプロファイルが存在すると推測してはいけません。
• 作成： name、shortName、idempotencyKey が必須です。shortName は 3～11 文字の英字、数字、またはスペースで、少なくとも 1 文字の英字を含める必要があります。任意の引数は description、smsCountry、smsNumberType、smsSenderValue、smsAreaCodes、compliance です。smsCountry を指定する場合は smsNumberType も必要です。省略すると、組織の共有ルートが使用されます。専用 SMS 市場の場合は、まず sent-compliance で要件を確認し、セットアップ計画を完成させてください。プロビジョニングによって番号が確保され、登録料が発生する場合があります。WhatsApp、RCS、請求、ドキュメントのアップロード、継承フラグ、サンドボックスの引数は、この MCP 作成ツールでは公開されていません。必須ドキュメントのアップロードが必要な場合、書き込み前に処理がブロックされます。ダッシュボードまたは文書化された REST フローを使用してください。使い捨て API キーは返されません。
• 更新： 正確な対象を取得してから、id と、name、shortName、description のうち変更するフィールドだけを指定します。省略したフィールドは変更されません。description: null を明示すると、説明が消去されます。名前と短縮名は消去できません。少なくとも 1 つのフィールドが必要です。省略したフィールドに null を設定したり、これによってチャネル設定が更新されると想定したりしてはいけません。
• 削除： 対象を取得して、削除内容を事前に確認します。削除によって WhatsApp が切断され、番号が解放され、稼働中のルートが無効になる可能性があることを説明してください。id と空でない idempotencyKey を指定します。deleted: false は、所有する一致プロファイルが削除されなかったことを意味しますが、別のテナントのプロファイルが存在する証拠にはなりません。

作成、更新、削除のいずれの場合も、組織、正確な対象またはペイロード、副作用を事前に確認し、呼び出しの直前に明示的な確認を求めてください。変更があれば確認は無効になります。再試行するたびに、新たな事前確認と承認が必要です。

作成と削除では、永続的なレシートを使用します。同じ意図の操作では、元のキーと引数を再利用してください。タイムアウト後や処理中の結果が返された後に、新しいキーを生成してはいけません。まず一覧取得／取得と返されたレシートの案内を確認してください。異なる引数でキーを再利用すると、要求は拒否されます。中断されたプロビジョニングや削除への対応が必要な場合は、自動で再試行したりキーを置き換えたりせず、処理を停止してダッシュボードで状況を調整してください。既存の結果を調整した後に限り、新しいキーで別の操作を実行できます。返されたプロファイルとチャネルの準備状況を確認してください。作成しただけでは、送信権限は付与されません。

MCP には、プロファイルの完了、キャンペーン管理、ユーザー管理、市場追加のためのツールはありません。これらの作業には、ダッシュボードまたは別途文書化された REST ワークフローを使用してください。存在しないツールを作り出してはいけません。

より広範な REST ワークフロー

以下の /v3/profiles に関するガイダンスは、レガシー REST のライフサイクルとそのコールバックを説明するものであり、sender_profiles.* の引数ではありません。新しい REST プロファイルのプロビジョニングでは、最新の API リファレンスで /v3/sender-profiles を確認してください。パス、スネークケースの REST フィールド、レガシーの完了時の動作を MCP 呼び出しに機械的に置き換えないでください。

プロビジョニングの手順

1. 認証情報を確認します。 POST /v3/profiles には admin 権限を持つ組織キーが必要です。プロファイルスコープのキーではプロファイルを作成できず、x-profile-id を送信するプロファイルキーには 403 が返されます。
2. 呼び出しの前に、継承と共有を決定します。 これらのフラグはコンプライアンスの姿勢を左右し、後から元に戻すのは困難です。
3. プロファイルを作成します。 ペイロードの形式が不確かな場合は、まず "sandbox": true で検証してください。サンドボックスの成功レスポンスは 24 時間キャッシュされるため、本番環境で作成する際は別の冪等性キーを使用してください。
4. 3 つのサポート対象の方法のうち、いずれか 1 つだけで WhatsApp を接続または継承します。
5. プロファイルの配下に、米国 SMS 用のキャンペーンを登録します。
6. 到達可能な webHookUrl を指定して、POST /v3/profiles/{profileId}/complete でプロファイルを完了させます。
7. コールバックからステータスを照合します。コールバックを受信できなかった場合は、ポーリングで確認します。
8. 最小権限のロールを使用してユーザーを招待します。

作成ペイロードの要点

必須フィールドは name のみです。影響の大きいオプションフィールドは、ID、共有、継承、請求、WhatsApp、ブランドに分類されます。

{
  "name": "Northwind Retail",
  "short_name": "Northwind",
  "description": "Retail brand tenant",
  "allow_contact_sharing": false,
  "allow_template_sharing": false,
  "inherit_contacts": false,
  "inherit_templates": false,
  "inherit_tcr_brand": true,
  "inherit_tcr_campaign": true,
  "billing_model": "profile",
  "billing_contact": {
    "name": "Ada Ops",
    "email": "[email protected]",
    "phone": "+14155550100",
    "address": "1 Example Way, Springfield"
  },
  "sandbox": true
}

short_name は、文字、数字、スペースを使った 3～11 文字で、少なくとも 1 文字はアルファベットである必要があります。継承フラグのデフォルト値は true であるため、フラグを指定せずに作成したプロファイルは、組織の連絡先、テンプレート、ブランド、キャンペーンを使用します。この例では、連絡先とテンプレートを明示的に分離しつつ、組織のコンプライアンス登録情報は継承します。共有フラグはこのプロファイルのリソースを外部に公開し、継承フラグは組織のリソースを内部に取り込みます。両者は別々の方向を示すもので、混同されることがよくあります。

作成時に必要なのは name だけですが、完了には short_name、description、プロファイルの KYC 情報、および必要なキャンペーンやチャネルの設定も必要です。inherit_tcr_brand が true の場合、プロファイル自体には KYC の提出が必要であるにもかかわらず、API は作成リクエスト内の brand オブジェクトを拒否します。完了エンドポイントを呼び出す前に、ダッシュボードでこの KYC を完了させてください。

billing_model には profile、organization、profile_and_organization を指定できます。profile を含むモデルでは、billing_contact がまだ設定されていない場合にこれが必要です。また、payment_details はこれらのモデルでのみ受け付けられます。カードのフィールドは決済処理業者に転送されるため、アプリケーション内のどこにも記録、エコー、永続化しないでください。

フィールドごとのルール、エラーコード、更新専用フィールドについては、references/profile-lifecycle.md を参照してください。

継承の判断

フラグ	true の意味	結果
inherit_tcr_brand	組織の登録済みブランドを使用する	同じリクエスト内の brand オブジェクトは拒否されます
inherit_tcr_campaign	組織のキャンペーンを使用する	これらのキャンペーンはこのプロファイルでは読み取り専用となり、作成しようとすると検証エラーが返されます
inherit_contacts	組織の連絡先を読み取る	テナント間で連絡先が分離されません
inherit_templates	組織のテンプレートを読み取る	テナント間でテンプレートが分離されません

inherit_tcr_campaign: false を指定してブランドを継承する方法はサポートされており、一般的なパターンです。法的なIDを共有しつつ、テナントごとに専用のメッセージング用途を設定できます。

WhatsApp：3 つの方法のみ

1. Sent Dashboard で実施する組織の Embedded Signup。このフローを開始する公開エンドポイントはありません。
2. 子プロファイルの継承 — 組織に WABA がある場合は、whatsapp_business_account を省略します。
3. 専用プロファイルの認証情報 — waba_id と access_token を指定した whatsapp_business_account を渡します。必要に応じて phone_number_id も指定できます。

POST /v3/profiles で認証情報を指定しても、Embedded Signup エンドポイントにはなりません。組織に WABA が設定されていない状態で whatsapp_business_account を省略すると、422 が返されます。組織の Embedded Signup を完了するか、有効な直接認証情報を指定してください。運用上のサインアップフローには waba-embedded-signup を使用します。

完了とステータス

POST /v3/profiles/{profileId}/complete では webHookUrl が必要です。

{
  "webHookUrl": "https://provisioning.example.com/callbacks/profile-complete",
  "sandbox": false
}

202 は処理が開始されたことを示し、最終ステータスは含みません。200 はプロファイルがすでに完了していることを示し、その本文にステータスが含まれます。コールバック本文は {profileId, success, status, timestamp} で、再試行なしで一度だけ配信されるため、呼び出し前に受信側が稼働している必要があります。また、フローは GET /v3/profiles/{profileId} のポーリングにフォールバックできるようにしてください。このコールバックは、サブスクライブした Sent Webhook とは別のものであり、Webhook HMAC ヘッダーが含まれるとは文書化されていません。プロビジョニング記録に紐づく一意のコールバックパスを使用し、不明なプロファイル ID を拒否して、復旧時にはポーリングを信頼できる手段として扱ってください。

プロファイルのステータスの表記は、各画面で異なります。作成レスポンスでは小文字の incomplete、完了時の 200 では小文字の completed、完了コールバックでは COMPLETED、SUBMITTED、failed が使われ、GET /v3/profiles/{id} では approved、submitted、processing、failed が文書化されています。固定された列挙値の集合として扱わず、小文字に正規化して固定の集合と照合することも避け、各値がどの画面から返されたかを記録してください。ステータスの比較では大文字と小文字を区別せず、不明な文字列はそのまま保持してください。

プロファイルごとのキャンペーン

キャンペーン管理はプロファイル配下にあります。エンドポイントは GET|POST /v3/profiles/{profileId}/campaigns と PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId} です。ブランド単独のエンドポイントはありません。専用ブランドはプロファイルとともに作成されます。

{
  "campaign": {
    "name": "Northwind order notifications",
    "description": "Order and delivery notifications for opted-in Northwind customers.",
    "type": "App",
    "useCases": [
      {
        "messagingUseCaseUs": "ACCOUNT_NOTIFICATION",
        "sampleMessages": [
          "Northwind: Your order 12345 has shipped. Reply STOP to opt out."
        ]
      }
    ],
    "volume": "1500",
    "messageFlow": "Customers opt in at checkout before notifications begin.",
    "privacyPolicyLink": "https://example.com/privacy",
    "termsAndConditionsLink": "https://example.com/terms"
  }
}

messagingUseCaseUs は 13 個の値から 1 つを受け付けます。sampleMessages には、各 1,024 文字以下のエントリを 1～5 件設定できます。数値を表す volume 文字列が 2,000 未満の場合は低ボリューム層、2,000 以上の場合は標準層が選択されます。キャンペーンのステータスは SENT_CREATED、ACTIVE、EXPIRED です。ユースケースの選択とサンプル文面のポリシーには sms-10dlc-registration を使用してください。

ユーザーとロール

アクセスを管理する操作は 5 つあります。GET /v3/users、POST /v3/users（招待）、GET /v3/users/{userId}、PATCH /v3/users/{userId}（ロール）、DELETE /v3/users/{userId} です。いずれも MCP 経由では利用できません。割り当て可能なロールは admin、billing、developer です。owner は作成アカウントに暗黙的に付与され、一覧には表示されません。変更には admin が必要です。

ロールの確認は、API キーを所有するメールアドレスを基準に行われます。所有者、または許可されたロールを持つアクティブユーザーだけが合格します。invited、suspended、rejected のユーザーは合格しません。組織レベルのアクセス権は子プロファイルにも継承されます。招待の有効期限は 7 日間です。既存のユーザーを招待すると 409 が返されます。

ユーザーを変更する前に、現在の状態を読み取り、その後、オペレーターに明示的な確認を求めてください。API は、自分自身のロール変更、最後の admin の降格、自分自身の削除、最後の admin の削除を拒否しますが、事前に確認すれば、検証エラーではなく明確な説明を提示できます。ロールの全組み合わせとキーの衛生管理ルールについては、references/users-and-roles.md を参照してください。

API キーを一覧表示、作成、取り消すエンドポイントはありません。キー管理はダッシュボードで行います。キーをローテーションするには、新しいキーを作成し、デプロイして、GET /v3/me で確認した後、古いキーを無効化または削除します。ただし、キーが侵害された場合に限り、先に削除してください。

マルチテナントのプロビジョニングに関する注意事項

Webhook イベントには、アプリケーションのテナント識別子は含まれません。初回送信の前に、message_id -> {tenant, profile, logical_send_id, channel} と receiving_number -> {tenant, profile} を永続化してください。多くのテナントプロファイルで同じ組織を共有できるため、account_id からテナントの所有権を推測しないでください。環境ごとに Webhook 登録を 1 つずつ設定し、下位環境の受信側に障害が発生しても本番環境が自動的に無効化されないようにしてください。

境界

分離、認証情報、影響範囲に関する設計上の判断には sender-profile-architect を、WhatsApp のサインアップフローには waba-embedded-signup を、ブランド審査とキャンペーンポリシーには sms-10dlc-registration を、メッセージイベントを購読する受信側には sent-webhook-engineer を使用してください。プロファイル完了コールバックには、このスキルの別途記載されている検証およびポーリングのガイダンスを使用してください。