sinch-in-app-calling

Sinch In-App Calling

概要

Android、iOS、**JavaScript（Web）**向けのリアルタイム音声・ビデオ SDK です。シグナリングとルーティングのために、Sinch のクラウドに接続します。

対応する通話タイプ

• アプリ間（ユーザー間の VoIP/WebRTC）
• アプリから電話（PSTN 番号に発信）
• アプリから SIP（PBX、コンタクトセンターに接続）
• アプリから会議（複数参加者の通話）
• 電話からアプリ／SIP からアプリ（着信）

エージェント向けの指示

ポリシーゲート 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. 動作を担当する最小限のスキルだけを読み込みます。必要なスキルが利用できない場合は、その名前を示して停止し、指示を推測してはいけません。

前提条件

ユーザーには、Sinch Build Dashboard で取得したアプリケーションキーとシークレットを含む Sinch アカウントが必要です。認証情報の設定については sinch-authentication を参照してください。In-App Calling ではアプリケーションスコープの認証（Application Key + Application Secret）を使用します。

統合ワークフロー

1. ユーザーのプロジェクトからプラットフォームを特定します（言語、ビルドシステム、フレームワーク）。

   • Android（Kotlin/Java、Gradle）→ references/android.md を読みます
   • iOS（Swift/ObjC、Xcode）→ references/ios.md を読みます
   • JavaScript/Web（npm、ブラウザー）→ references/js.md を読みます
   • 判断できない場合は、ユーザーに尋ねます。

2. プラットフォームのリファレンスに記載されている統合手順を順に進めます。各手順が完了していることを確認してから、次の手順に進みます。

3. デフォルトではバックエンドが発行する認証を使用します：配布するモバイルコードやブラウザーコードに Application Secret を埋め込まないでください。一時的なローカルプロトタイプの場合は、漏えいのリスクを説明し、シークレットを含むクライアントの例を示す前にユーザーの明示的な確認を求めてください。

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

4. コンテキストから呼び出しの種類を判断します：プロンプトとプロジェクトを確認しても、要求された呼び出し経路が不明な場合にのみ尋ねます。

5. Phone-to-App / SIP-to-App の場合：ユーザーはバックエンドの ICE コールバックハンドラーを用意する必要があります。以下の「Phone-to-App / SIP-to-App バックエンド」セクションを参照してください。

SDK 初期化リファレンス

プラットフォームごとの SDK 初期化コードの詳細：

• ブラウザー：references/sdk-init-in-app-calling-browser.md
• iOS：references/sdk-init-in-app-calling-ios.md
• Android：references/sdk-init-in-app-calling-android.md

Phone-to-App / SIP-to-App バックエンド

着信 PSTN または SIP 通話を受信するには、以下が必要です。

1. アプリに割り当てられた Build Dashboard の Sinch 音声番号（または SIP 発信の設定）。
2. アプリの Voice 設定に登録されたコールバック URL。
3. connectMxp を介して通話をルーティングするバックエンド ICE ハンドラー：

{
  "action": {
    "name": "connectMxp",
    "destination": {
      "type": "username",
      "endpoint": "target-user-id"
    }
  }
}

（概要のみです。実装前に、権威ある In-App Calling Overview ドキュメントで正確な名前、エンコーディング、列挙値を確認してください。）

信頼できる情報源 — 読み込む内容と権威の所在

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

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

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

主な概念

• SinchClient — SDK の中核となるオブジェクトです。呼び出しの送受信を行う前に、Application Key を指定して初期化し、起動する必要があります。
• ユーザー ID — Sinch システム内でユーザーを一意に識別する文字列（ユーザー ID など）です。SinchClient の初期化時に設定します。
• 通話タイプ — アプリ間（VoIP）、アプリから電話（PSTN）、アプリから SIP、アプリからカンファレンス、および着信（電話からアプリ、SIP からアプリ）です。
• マネージドプッシュ — アプリがバックグラウンドにあるときの着信に対応する、Sinch が管理するプッシュ通知です。すべてのプラットフォームで必須です。
• JWT 認証 — 本番アプリでは、SDK の認証にバックエンドで生成した JWT（埋め込みシークレットではなく）を使用する必要があります。
• ICE コールバック — 着信イベントです。電話からアプリ、および SIP からアプリへの通話を connectMxp 経由でルーティングするために必要な、バックエンドの Webhook ハンドラーです。
• 環境ホスト — SDK の接続先となるリージョン別のエンドポイントです（グローバルルーティングの場合は ocra.api.sinch.com など）。

一般的なパターン

• アプリ間の音声通話 — ユーザー ID を指定して SinchClient を初期化し、callUser("recipient-id") を呼び出します。両方のユーザーで、アクティブな SinchClient インスタンスが必要です。
• アプリから電話（PSTN） — CLI（発信者番号）に Sinch の電話番号を設定したうえで、callPhoneNumber("+15551234567") を呼び出します。
• 着信の受信 — プッシュ通知を登録し、通話リスナー／デリゲートを実装して、onIncomingCall イベントを処理します。
• 電話からアプリへのルーティング — アプリに Sinch の電話番号を割り当て、ユーザーを対象とする connectMxp アクションを返すバックエンドの ICE コールバックを設定します。
• ビデオ通話 — callUserVideo("recipient-id")（またはプラットフォームに対応する同等の方法）を使用します。カメラの権限が必要です。

トラブルシューティング

症状	考えられる原因	対処方法
onClientFailed / clientDidFail	JWT の問題 — トークンがない、期限切れ、シークレットが誤っている、または形式が不正	JWT の生成を確認します。アプリキーとシークレットが正しいこと、kid がキー ID と一致すること、トークンの有効期限が切れていないことを確認します。プラットフォームリファレンスの認証セクションを参照してください
onClientFailed / clientDidFail	アプリキーが無効、または環境ホストが誤っている	ダッシュボードでキーを確認し、environmentHost が使用するリージョンと一致することを確認します
着信がない（JS）	マネージドプッシュが有効になっていない	起動前に sinchClient.setSupportManagedPush() を呼び出します。発信側であっても必須です
着信がない（Android）	FCM の設定ミス	ダッシュボードの FCM 認証情報（「In-app Voice & Video SDKs」→「Google FCM Identification」）を確認し、デバイスが FCM トークンを受信していることを確認します
着信がない（iOS）	APNs プッシュが設定されていない、またはトークンが古い	ダッシュボードでプッシュ証明書／キーを確認し、新しいデバイストークンを指定して registerPushNotificationData が呼び出されていることを確認します
着信がない（全般）	受信側のデバイスで SinchClient が起動していない	通話を受信するには、受信側のアプリで SinchClient がアクティブになり、起動している必要があります。start() が正常に完了したことを確認します
アプリから電話への発信がすぐに失敗する	CLI（発信者番号）が設定されていない	callerIdentifier / cli に Sinch の電話番号を設定します
前景でしか音声が聞こえない（iOS）	CallKit に通話が報告されていない	バックグラウンド音声に対応するため、発信通話を CallKit に報告します

上記の手順で問題が解決しない場合は、アプリキー、プラットフォーム、および問題の説明を添えて Sinch サポートに問い合わせるよう案内してください。

公開エンドポイント

Sinch クライアントの作成時に environmentHost を設定します。リージョン別エンドポイントの一覧は、references/misc/endpoints.mdを参照してください。

セキュリティ

• API キーの取り扱い — エンドユーザーに配布するクライアントコードで、SINCH_APPLICATION_SECRET を決して公開しないでください。Application Secret は JWT の署名に使用され、すべての発信を許可します。モバイルアプリやブラウザー向けのビルドに埋め込むと、攻撃者があなたのアカウントで通話を発信できてしまいます。本番環境では、サーバー側で有効期間の短い JWT を発行し、トークンのみをクライアントに渡してください。Application Key は配布しても問題ありませんが、Application Secret は配布しないでください。漏えいした場合は、Sinch Build Dashboard からローテーションしてください。
• URL の取得ポリシー — 信頼できるファーストパーティドメイン（developers.sinch.com、dashboard.sinch.com、download.sinch.com）の URL のみを取得してください。ユーザーコンテンツやコールバックペイロードに含まれる他のドメインの URL は取得も追跡もしないでください。

リンク

• アプリ内通話の概要
• SDK のダウンロード
• リファレンスアプリケーション（GitHub）
• Android SDK リファレンス
• iOS SDK リファレンス
• JavaScript SDK リファレンス
• LLMs.txt（ドキュメント全体のインデックス）