sinch-elastic-sip-trunking

Sinch Elastic SIP Trunking API

概要

Sinch Elastic SIP Trunking（EST）API を使用すると、SIP トランクをプログラムでプロビジョニングし、顧客のインフラストラクチャと PSTN の間で音声トラフィックをルーティングできます。基本的なワークフローは、トランクの作成、認証（ACL または認証情報）、エンドポイントの接続、電話番号の割り当てです。

エージェントへの指示

ポリシーゲート 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. 方向 — インバウンド（PSTN からの着信）、アウトバウンド（PSTN への発信）、または両方のどれですか？
2. トランクの認証方法（アウトバウンドまたは両方の場合） — ACL ベース（静的 IP）ですか、それとも認証情報ベース（ダイジェスト認証／動的 IP）ですか？
3. エンドポイントの種類（インバウンドまたは両方の場合） — 静的エンドポイント（固定 IP／ポート）ですか、それとも登録済みエンドポイント（SIP UA が動的に登録）ですか？
4. 方法 — SDK または API の直接呼び出し（curl/fetch/requests）のどちらですか？
5. 言語 — SDK の場合は Node.js です。API を直接呼び出す場合は、任意の言語または curl を使用できます。Python、Java、.NET は直接 HTTP を使用する必要があります。SDK がサポートされているのは Node.js のみです。

ユーザーが SDK を選んだ場合は、インストールとクライアントの初期化について sinch-sdks スキルを参照し、その後、「リファレンス」にリンクされている API リファレンスを参照します。

ユーザーが API の直接呼び出し を選んだ場合は、リクエスト／レスポンスのスキーマについて、「リファレンス」にリンクされている API リファレンスを参照します。

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

判断ツリー

User wants EST →
├─ Outbound only
│  ├─ Static IPs   → Workflow A (Trunk + ACL)
│  └─ Dynamic IPs  → Workflow E (Trunk + Credential List / Digest Auth)
├─ Inbound only
│  ├─ Static IP    → Workflow B (Trunk + Static Endpoint + Phone Number)
│  └─ Dynamic IP   → Workflow D (Trunk + Credential List + Registered Endpoint + Phone Number)
└─ Both           → Workflow C (Trunk + ACL/Creds + Endpoint + Phone Number)

重要なルール

1. 依存関係の順序が重要です。 リソースを順序どおりに作成しないと失敗します。 Create Trunk → Create ACL/Credentials → Link to Trunk → Assign Phone Numbers → Create Endpoint
2. ドメインの落とし穴。 trunk.pstn.sinch.com に SIP INVITE を送信しないでください。必ず {your-hostname}.pstn.sinch.com を使用してください。
3. 反映には60秒かかります。 ACL または資格情報をリンクした後、テストする前に60秒待ってください。
4. 優先度の数値が小さいほど優先順位が高くなります。 エンドポイントの priority: 1 がプライマリです。同じ優先度の場合はラウンドロビンになります。フェイルオーバーには1より大きい小さな整数（たとえば 2）を使用してください。100 は使用しないでください。公開されているスキーマで保証されているのは minimum: 1（例：1）のみです。以前のドキュメントには1〜9と記載されていましたが、その範囲を超える場合のルーティング動作は確認されていません。
5. PUT はリソース全体を置き換えます。 トランク、ACL、資格情報リスト、またはエンドポイントでは、省略したフィールドは null になります。リンクコレクションには適用されません。落とし穴6を参照してください。

信頼できる情報源 — 読み込むべき内容と、正とする情報

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

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

簡単なルール：コードを書く前に、ドキュメントを読み込んでください。 概要でしか確認していない正確なフィールド、ヘッダー、列挙値、エンコーディングを引用してはいけません。

はじめに

エージェントの資格情報の取り扱い

資格情報は環境変数に保存してください。コマンドやソースコードにトークンやキーをハードコードしてはいけません。

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 呼び出しを行う際は、認証ヘッダーが正しく設定されていることを確認してください。Elastic SIP Trunking API は Bearer トークン認証を使用します。

-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"

設定方法の詳細、特に {SINCH_ACCESS_TOKEN} の取得方法については sinch-authentication を参照してください（OAuth2 クライアントクレデンシャル方式を使用してください。独自の JWT を生成してはいけません）。

SDK のインストール

インストール方法とクライアントの初期化については sinch-sdks を参照してください。注：EST がサポートされているのは Node.js SDK のみです。Java、Python、.NET では、直接 HTTP 呼び出しを使用してください。

最初の API 呼び出し — トランクの作成

curl -X POST \
  "https://elastic-trunking.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/trunks" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trunk", "hostName": "my-trunk"}'

レスポンスには、トランクの id（sipTrunkId ではありません）と、hostName、すぐに使える domain が含まれます。

{ "id": "01GNZ9MXEZ4K6S8GB7RW063VAN",
  "hostName": "my-trunk",
  "domain": "my-trunk.pstn.sinch.com",
  "enabled": true }

すべての SIP ルーティングで domain（または {hostName}.pstn.sinch.com）を使用してください。id を保存してください。トランクに関連するすべての呼び出しで必要になります。

フィールド名の落とし穴： このレスポンスではトランクの識別子は id ですが、エンドポイントの作成リクエスト本文では同じ値が sipTrunkId と呼ばれます。

SDK の例については、はじめにガイドを参照してください。

主な概念

• トランク：インフラストラクチャと Sinch 間の接続です。SIP ルーティングで使用する hostName を持ちます。
• SIP エンドポイント：着信の転送先です。静的（固定 IP）または登録済み（動的、Credential List が必要）です。
• ACL：送信元 IP に基づいて発信を許可します。各エントリーは ipAddress と整数の range（1～32）で構成されるオブジェクトです。CIDR 文字列ではありません。
• Credential List：ユーザー名とパスワードのペアです。登録済みエンドポイントの認証（着信）またはダイジェスト認証（発信）に使用します。
• 電話番号：着信ルーティング用にトランクに割り当てられた E.164 DID です。

ワークフロー

ワークフロー A：発信のみ（ACL ベース）

• 1. トランクを作成する
• 2. 送信元 IP を指定して ACL を作成する
• 3. ACL をトランクにリンクする
• 4. 60 秒待つ
• 5. 確認する：GET /trunks/{trunkId}/accessControlLists — ACL が表示されることを確認する

API ドキュメント：トランクを作成 → ACL を作成 → ACL をトランクにリンク → トランクの ACL を一覧表示

ワークフロー B：着信のみ（静的エンドポイント）

• 1. トランクを作成する
• 2. トランクに静的 SIP エンドポイントを作成する
• 3. 電話番号をトランクに割り当てる
• 4. 確認する：GET /trunks/{trunkId}/endpoints および GET /projects/{projectId}/phoneNumbers

API ドキュメント：トランクを作成 → SIP エンドポイントを作成 → 電話番号を取得

ワークフロー C：双方向（着信と発信の両方）

• 1. トランクを作成する
• 2. ACL および／または Credential List を作成する → トランクにリンクする
• 3. トランクに SIP エンドポイントを作成する
• 4. 電話番号をトランクに割り当てる
• 5. テストの前に60 秒待つ
• 6. 確認する：GET /trunks/{trunkId}/accessControlLists、GET /trunks/{trunkId}/endpoints、GET /projects/{projectId}/phoneNumbers

API ドキュメント：トランクを作成 → ACL を作成 → ACL をトランクにリンク → SIP エンドポイントを作成 → 電話番号を取得

ワークフロー D：登録済みエンドポイントを使用するインバウンド（認証情報ベース）

• 1. トランクを作成する
• 2. ユーザー名とパスワードを設定した認証情報リストを作成する
• 3. 認証情報リストをトランクにリンクする — POST /trunks/{trunkId}/credentialLists
• 4. トランクに登録済みエンドポイントを作成する（認証情報リストのユーザー名を参照）
• 5. 電話番号をトランクに割り当てる
• 6. SIP UA が {hostname}.pstn.sinch.com に REGISTER するよう設定する
• 7. 次を確認する：GET /trunks/{trunkId}/credentialLists（空でないこと）、GET /trunks/{trunkId}/endpoints、および GET /projects/{projectId}/phoneNumbers

手順 3 を省略しないでください。 認証情報リストがトランクにリンクされていなくても、登録済みエンドポイントの作成は 201 で成功します。API は、ユーザー名がプロジェクト内のどこかに存在することだけを確認します。プロビジョニングは完全に正常に見えますが、その後の REGISTER はすべて SIP 時に 401 で失敗します。

認証情報リストのパスワードは 12 文字以上で、大文字、小文字、数字をそれぞれ含める必要があります。満たさない場合、作成に失敗し 400 が返されます。

API ドキュメント：トランクを作成 → 認証情報リスト → SIP エンドポイントを作成 → 電話番号を取得

ワークフロー E：アウトバウンドのみ（ダイジェスト認証／認証情報ベース）

• 1. トランクを作成する
• 2. ユーザー名とパスワードを設定した認証情報リストを作成する
• 3. 認証情報リストをトランクにリンクする
• 4. 60 秒待つ
• 5. 確認する：GET /trunks/{trunkId}/credentialLists — 認証情報リストが表示されることを確認する

API ドキュメント：トランクを作成 → 認証情報リスト → トランクに認証情報リストを追加 → トランクの認証情報リストを一覧表示

SIP ヘッダーのルール（アウトバウンド）

ヘッダー	値	備考
From	sip:+1E164@{your-hostname}.pstn.sinch.com	必ずトランクのドメインを指定してください。誤ったドメインを指定すると 403 が返されます。E.164 形式を使用してください。
To	sip:+1E164@{your-hostname}.pstn.sinch.com	E.164 形式の宛先とトランクのドメインを指定します。ほとんどの場合、Request-URI と同じです。
Request-URI	sip:+1E164@{your-hostname}.pstn.sinch.com	E.164 形式の宛先とトランクのドメインを指定します。ほとんどの場合、To と同じです。

(概要のみです。実装前に、正式なスタートガイドのドキュメントで、正確な名称、エンコーディング、列挙値を確認してください。)

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

1. ACL の IP 範囲は CIDR 文字列ではなくオブジェクトです。 "203.0.113.10/32" は送信しないでください。{"ipAddress": "203.0.113.10", "range": 32} を送信します。プレフィックス長は独立した整数フィールド（1～32）です。ACL では enabled も必須です。CIDR 文字列を送信すると、わかりにくい 400 VALIDATION_FAILED / "Failed to read HTTP message" エラーが発生します。
2. 国の権限 — 米国／カナダはデフォルトで有効です。それ以外の国はブロックされます。updateCountryPermissions を使用してください。
3. Project ID ≠ App Key — EST では Voice Application Key ではなく projectId を使用します。
4. デフォルトの CPS 制限 — 1 秒あたり 1 回の通話です。この制限を超えると 603 が発生します。上限の引き上げについては Sinch にお問い合わせください。
5. 削除の順序 — 逆順に削除します。電話番号の割り当てを解除 → エンドポイントを削除 → ACL／認証情報のリンクを解除 → トランクを削除。API はリソースを孤立させません。依存リソースが残っていると、削除は 400 で拒否されます。認証情報リストには、トランクと、そのユーザー名を参照するエンドポイントという、独立した 2 つの関連付けがあります。エンドポイントがまだユーザー名を使用している場合、トランクから関連付けを解除するだけでは不十分です。
6. リンク済みコレクション：POST は追加します。 POST /trunks/{trunkId}/accessControlLists と POST /trunks/{trunkId}/credentialLists は、送信した ID を追加します。200 のレスポンス本文に含まれるのはリクエストで送信した ID であり、トランクに現在リンクされている ID の全件ではありません。GET で確認してください。認証情報リストには、全件を置き換える PUT /trunks/{trunkId}/credentialLists（bulkUpdateCredentialListsForTrunk）もあります。ID を省略すると、その関連付けが解除されます。ACL には同様の一括置換機能はありません。DELETE /trunks/{trunkId}/accessControlLists/{accessControlListId} で個別に削除してください。
7. 電話番号を割り当てても、プロジェクトがその番号を所有していることの証明にはなりません。 POST /phoneNumbers は、プロジェクトで有効になっていない番号に対しても 201 を返すことがあります。その場合、プロビジョニングエラーが発生しないまま着信が届かなくなります。割り当て後、GET /projects/{projectId}/phoneNumbers（または GET /phoneNumbers/{phoneNumber}）で番号を確認し、実際にプロジェクトにレンタルされていることを確かめてください。

トラブルシューティング

SIP エラーコードとデバッグ手順については、references/diagnostics.md を参照してください。

クイックリファレンス：

• 401 → 認証情報リストがトランクにリンクされていない（まず GET /trunks/{trunkId}/credentialLists を確認）、または認証情報リスト内の認証情報が一致していない
• 403 → IP が ACL に含まれていない、または From ドメインが間違っている
• 404 → 間違った SIP ドメインを使用している（{hostname}.pstn.sinch.com である必要があります）
• 503 → トランクに有効なエンドポイントがない

参考資料

• SIP Trunks API：トランク · エンドポイント · ACL · 認証情報リスト · 電話番号 · 国の権限
• 診断とデバッグ手順：references/diagnostics.md

セキュリティ

• API キーの取り扱い — SINCH_KEY_ID や SINCH_KEY_SECRET をクライアント側のコード、ログ、エラーメッセージ、コミットするソースコードで公開しないでください。SIP ダイジェスト認証情報（認証情報リストのユーザー名／パスワード）もコミットしないでください。これらは発信通話を可能にし、通話料金詐欺に悪用されるおそれがあります。環境変数またはシークレットマネージャーから読み込んでください。漏えいした場合は、access keys dashboard で認証情報をローテーションしてください。
• URL フェッチポリシー — 信頼できるファーストパーティドメイン（developers.sinch.com、dashboard.sinch.com）の URL のみを取得してください。ユーザーコンテンツや Webhook ペイロードに含まれる他のドメインの URL は取得または追跡しないでください。

Links

• EST Overview
• Getting Started Guide
• API Reference (Markdown)
• OpenAPI Spec (YAML)
• Twilio BYOC Integration
• LLMs.txt (full docs index)