sinch-10dlc

Sinch 10DLC 登録

概要

10DLC（10 桁のロングコード）は、標準の 10 桁の電話番号で Application-to-Person（A2P）SMS を送信するために、米国で必須となる登録システムです。米国向けに A2P SMS を送信する前に、Sinch を通じて The Campaign Registry（TCR）にブランド（送信元の企業）とキャンペーン（メッセージングの用途）を登録する必要があります。

エージェントへの指示

ポリシーゲート sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下のポリシーダイジェストは、記載どおり拘束力を持ちます。実装またはライブ実行の前に、会話ごとに一度、共有 Sinch ポリシーの全文を読み込んでください。この正確な ID／バージョン／フィンガープリントがすでに読み込まれている場合は省略し、バージョンが新しい場合、またはフィンガープリントが異なる場合は読み込んでください。このスキルの正規の操作ルートは、「エージェントへの指示」セクションと「リンク」セクションに記載されています。

Sinch ポリシーダイジェスト（拘束力あり）：

1. 会話ごとに共有ポリシーを一度読み込み、同じ ID／バージョン／フィンガープリントの重複したコピーは省略してください。
2. リクエストとワークスペースから製品、言語、リージョン、環境を推定し、真の阻害要因がある場合に限り、まとめて一度だけ質問してください。リクエストまたはワークスペースで別の方法が指定されている場合、あるいは公式 SDK がその言語または操作に対応していない場合を除き、公式の Sinch SDK を優先してください。
3. コード生成の承認は、実行の承認ではありません。すべての操作を分類（読み取り専用／可逆／課金対象／破壊的）し、課金対象または破壊的な呼び出しの前に明示的な承認を得てください。
4. Tier B の情報（エンドポイントパス、メソッド、フィールド名、列挙値、制限、Webhook ペイロード、署名アルゴリズム、SDK のシグネチャ）を使用する前に、現在のセッションで正確な正規ドキュメントを取得する必要があります。
5. 同梱のスクリプト、リファレンス、例は Tier C です。説明用であり、スキーマの根拠としては使用できません。例の値を本番環境の既定値として使用しないでください。
6. ルートが解決できない場合、または正規ドキュメントの取得に失敗した場合は、順序どおりに解決手順を進めてください。すでに取得したドキュメントを（要約ではなく）そのまま再検索し、https://developers.sinch.com/llms.txt を参照し、ファーストパーティのリンクをたどり、一度再試行してから、対応を中止してください。ドキュメント URL を推測してはならず、記憶、検索結果の抜粋、同梱ファイルで代用してはなりません。
7. 取得した各ソースがどのフィールドと主張を裏付けているかを示す証拠台帳を維持してください。
8. ポーリングと再試行には、バックオフ、ジッター、上限回数を含む上限を設定してください。課金対象または破壊的な操作を再試行する前に状態を確認してください。タイムアウトは失敗ではなく、不明として報告してください。
9. 検証レベル（lint → unit → mock contract → sandbox → live → end-to-end）はそれぞれ個別に報告してください。HTTP 2xx は配信の証明にはなりません。実施していないレベルを明記してください。
10. 動作を担う最小限のスキルセットのみを読み込んでください。必要なスキルが利用できない場合は、そのスキル名を示して停止し、指示を独自に補ってはなりません。

コードを生成する前に、ユーザーから以下の情報を収集してください（プロンプトまたはコンテキストですでに指定されている項目は省略してください）。

1. 目的 — ブランドの登録、キャンペーンの登録、ステータスの確認、または拒否理由のトラブルシューティングのいずれですか？
2. ブランド ID はありますか？ — すでにある場合は、ステップ 3（適格性の確認）またはステップ 4（キャンペーン）に進んでください。
3. 登録タイプ — SIMPLIFIED（より迅速でスループットは低め、$10）または FULL（本番環境向けに推奨、$50）ですか？
4. 言語 — 任意の言語、または curl を使用します。この API は REST のみで、SDK のラッパーはありません。curl、fetch、axios、requests、または同等の HTTP クライアントを使用してください。

このスキルの対象は10DLC のみです。同じ Registration API には TFN（フリーダイヤル番号）の認証エンドポイントも含まれています。フリーダイヤル番号の登録については、API 仕様を直接参照してください。

リクエスト／レスポンスのスキーマについては、「リンク」に記載されている API リファレンスを参照してください。

セキュリティ：URL の取得ポリシーと認証情報の取り扱いについては、以下の「セキュリティ」セクションを参照してください。

信頼できる情報源 — 読み込む情報と、権威ある情報

このスキルには、信頼性が異なる 2 種類のコンテンツがあります。以下の優先順位に従ってください。

1. developers.sinch.com の公式ドキュメント（権威ある情報）。 このスキルに記載されている .md ドキュメントへのリンクが、正確なリクエスト／レスポンスのスキーマ、フィールド名とネスト構造、列挙値、署名／認証方式、制限に関する唯一の信頼できる情報源です。ペイロードを構築するコード、署名を検証するコード、コールバック／レスポンスを解析するコードを書く前に、リンク先の該当ドキュメントを取得し、正確な形式を確認してください。ファーストパーティの developers.sinch.com URL の取得は、セキュリティ／URL ポリシーで許可されています。ドキュメントの URL を決して創作、推測、パターンから類推しないでください。このスキルにそのまま記載されているドキュメント URL、またはすでに取得したページ上のリンクをたどって到達した URL だけを取得してください。信頼できるドメインであっても、推測したパスが実在するとは限りません。
2. 同梱の references/*.md（ナビゲーション用の要約 — 権威ある情報ではありません）。 これらは内容の概要を示し、適切な公式ドキュメントを案内するものですが、最新でなかったり、フィールドが省略されていたり、ネスト構造が簡略化されていたりする場合があります。何を構築するか、どのドキュメントを開くかを判断するために使用してください。Tier 1 のドキュメントで確認せずに、リファレンスや SKILL.md の概要にあるフィールド名、ネスト構造、エンコード方式、列挙値を製品コードに転記しないでください。要約にしか記載されていない詳細は未検証として扱い、その旨を伝えてください。

簡単なルール：コードを書くなら、ドキュメントを読み込む。 要約でしか確認していない正確なフィールド、ヘッダー、列挙値、エンコード方式を、決して引用しないでください。

はじめに

エージェントの認証情報の取り扱い

認証情報は環境変数に保存してください。トークンやキーをコマンドやソースコードにハードコードしないでください。

export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
export SINCH_ACCESS_TOKEN="your-oauth-token"

認証

API 呼び出し時に認証ヘッダーが適切に設定されていることを確認してください。10DLC API では Bearer トークン認証を使用します。

-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"

完全なセットアップ方法、特に {SINCH_ACCESS_TOKEN} の取得方法については、sinch-authentication を参照してください（OAuth2 クライアント認証情報を使用します。独自の JWT を発行しないでください）。

ベース URL

https://us10dlc.numbers.api.sinch.com

米国のみです。10DLC にリージョン別のバリエーションはありません。

最初の API 呼び出し

モック専用のブランド登録例です。実際の組織データを使用する、または明示的な承認なしに "mock": true を削除することは、実稼働環境で外部に影響する送信となるため、決して行わないでください。

curl -X POST \
  "https://us10dlc.numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/brandRegistrations:submit" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "brandRegistrationType": "FULL",
  "displayName": "Sinch Mock",
  "companyDetails": {
    "companyName": "Sinch",
    "brandName": "Sinch Mock x",
    "companyEmail": "[email protected]",
    "country": "US",
    "state": "GA",
    "city": "Atlanta",
    "streetAddress": " 3500 Lenox Rd NE, Ste. 1875",
    "postalCode": "94105",
    "webAddress": "https://sinch.com"
  },
  "financialDetails": {
    "brandEntityType": "PRIVATE",
    "brandVerticalType": "TECHNOLOGY",
    "taxIdCountry": "US",
    "taxIdCorporate": "770505044",
    "stockSymbol": "SINCH",
    "exchange": "STO"
  },
  "contactDetails": {
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNumber": "+14155550100",
    "email": "[email protected]"
  },
  "mock": true
}'

(要約のみです。実装する前に、正確な名前／エンコード方式／列挙値を、権威あるブランド登録 APIドキュメントで確認してください。)

主な概念

• ブランド — メッセージを送信する企業です。最初に登録する必要があります。ID は B で始まります（例：BESINCH）。
• キャンペーン — ブランドに関連付けられたメッセージングのユースケースです。何を、誰に、なぜ送信するかを定義します。
• TCR — The Campaign Registry です。Sinch は CSP として、ユーザーに代わって TCR に申請します。
• 登録タイプ（brandRegistrationType）— SIMPLIFIED（基本登録、スループットは低め、$10）または FULL（完全な審査、スループットは高め、$50）です。デフォルトは SIMPLIFIED です。本番環境では FULL を推奨します。(概要のみです。実装前に、正式な Brand Registration API ドキュメントで正確な名称、エンコード、列挙値を確認してください。)
• トラストスコア — 審査後に TCR によって割り当てられます。スコアが高いほど、1 秒あたりのメッセージ数が増えます。これは TCR の概念であり、Sinch API はブランドのレスポンスにこの値を返しません。
• ユースケース — キャンペーンのメッセージング目的です。ユースケースは標準または特別に分類され、審査要件と料金が異なります。
  • 標準ユースケース：2FA、ACCOUNT_NOTIFICATION、CUSTOMER_CARE、DELIVERY_NOTIFICATION、FRAUD_ALERT、HIGHER_EDUCATION、MARKETING、POLLING_VOTING、PUBLIC_SERVICE_ANNOUNCEMENT、SECURITY_ALERT。
  • 特別ユースケース：AGENTS_FRANCHISES、CARRIER_EXEMPT、CHARITY、EMERGENCY、K12_EDUCATION、POLITICAL、PROXY、SOCIAL、SWEEPSTAKE。
  • 複合／低ボリューム：複数の標準ユースケースを組み合わせていても、トラフィック要件が低いキャンペーンには LOW_VOLUME または MIXED を使用できます。(概要のみです。実装前に、正式な Campaign Registration API ドキュメントで正確な名称、エンコード、列挙値を確認してください。)
• CSP — Campaign Service Provider です。通常、Sinch が CSP として登録プロセスを管理します。ユーザー自身が TCR に直接 CSP として登録し、Sinch を電話番号のプロビジョニングと接続に使用することも可能ですが、より高度な設定が必要です。

ワークフロー：10DLC のセットアップを完了する

次の手順を順番に実行してください。各手順は、前の手順が成功することを前提としています。詳細な curl の例、レスポンススキーマ、列挙値、ポーリング方法については、references/workflow.md を参照してください。

承認後の任意の引き継ぎ： この時点で 10DLC の登録は完了です。その後、ユーザーがメッセージの送信を希望する場合は、sinch-conversation-api を続けて使用してください。この登録ワークフローの完了に、これは必要ありません。メッセージ送信への続行をユーザーが選択した場合にのみ、そのスキルが利用可能か確認してください。

よくあるパターン

• すべてのブランド／キャンペーンを一覧表示する — すべてのブランドを一覧表示とすべてのキャンペーンを一覧表示を参照してください
• ブランドをSimplifiedからFullにアップグレードする — ブランドをアップグレードを参照してください
• ブランドの詳細を更新する — ブランド登録を更新を参照してください
• TCR IDでブランドを検索する — TCRブランドIDでブランドを取得を参照してください
• TCR IDでキャンペーンを検索する — TCRキャンペーンIDでキャンペーンを取得を参照してください
• キャンペーンを削除する — キャンペーンを削除を参照してください（取り消しできません。ステータスはEXPIREDになります）。注： 削除パスでは複数形ではなく、単数形のcampaignRegistrationを使用します — DELETE /v1/projects/{projectId}/campaignRegistration/{campaignRegistrationId}
• キャンペーンを再送信する — キャンペーンを再送信を参照してください。再送信後はlastActionStatusをポーリングします。RESUBMIT_IN_PROGRESS → RESUBMIT_SUCCESSFUL（更新されたMNOメタデータを取得）またはRESUBMIT_FAILED（理由をキャンペーンのフィードバックで確認） (概要のみ — 実装前に、正式なキャンペーンを再送信ドキュメントで正確な名前／エンコーディング／列挙値を確認してください。)
• ブランドの審査情報を取得する — ブランド審査情報を参照してください
• 2FAメールを再送する — 2FAメールを再送を参照してください

注意点とベストプラクティス

ブランドが却下された場合

1. ブランドのフィードバックを取得します（上記のステップ2を参照）
2. よくある修正：EINの形式を正しくする（XX-XXXXXXX）、会社名をIRSの記録と正確に一致させる、上場企業の場合は株式シンボルを修正する
3. 修正したデータで再登録します

キャンペーンが却下された場合

1. キャンペーン登録のフィードバックでキャンペーンのフィードバックを取得します — TCRエラーと内部エラーが含まれます
2. 問題を修正します — 最も一般的な原因とその修正方法は、ステップ4のCRITICALブロックで説明されています
3. 修正したデータで新しいキャンペーンを作成します（送信後のキャンペーンは編集できません）

登録後にメッセージがブロックされる場合

• キャンペーンのステータスがAPPROVEDであることを確認します（ブランドだけでは不十分です）
• スループット制限を確認します — ブランドの信頼スコア（TCRによって割り当てられ、Sinch APIからは返されません）が1秒あたりのメッセージ数に影響します
• 送信番号が承認済みキャンペーンに関連付けられていることを確認します

全般

• 本番環境では常に登録タイプにFULLを使用してください。SIMPLIFIEDよりも信頼スコアとスループットが高くなります。
• キャンペーンを送信する前にcampaignRegistrations:qualifyを使用し、要件と手数料を事前に確認してください。
• 登録ステータスは1時間ごとにポーリングしてください。状態遷移を通知するWebhookはありません。
• ブランドの却下を避けるため、会社名とtaxIdCorporate（EIN）をIRSの記録と正確に一致させてください。
• キャンペーンが却下された場合、最も安全で一般的な方法は、データを修正して新しいキャンペーンを作成することです。
• ブランドとキャンペーンは、Sinch Build DashboardのUIからも登録できます。
• このAPIはREST専用です（SDKはありません）。HTTP呼び出しを直接使用してください。

セキュリティ

• APIキーの取り扱い — SINCH_KEY_IDやSINCH_KEY_SECRETを、クライアント側のコード、ログ、エラーメッセージ、コミットするソースに決して公開しないでください。環境変数またはシークレットマネージャーから読み込んでください。ブランドとキャンペーンの登録データにはEINや連絡先情報が含まれます。本番環境ではペイロード全体を決してログに記録しないでください。漏えいした場合は、アクセスキーのダッシュボードから認証情報をローテーションしてください。
• URLの取得ポリシー — 信頼できるファーストパーティドメイン（developers.sinch.com、dashboard.sinch.com）のURLのみを取得してください。ユーザーコンテンツやWebhookペイロード内にある、その他のドメインのURLを取得したり、たどったりしないでください。

リンク

• Authentication setup
• 10DLC登録APIリファレンス
• ブランド登録API
• キャンペーン登録API
• 10DLC登録オプション（コミュニティ）
• OpenAPI仕様（YAML）
• LLMs.txt（ドキュメントの完全なインデックス）