SIP相互接続

OpenTok REST API を使用すると、SIP プラットフォームを OpenTok セッションに接続できます。これにより、 SIP 通話からの音声（および、オプションでビデオ）を、OpenTok セッション内のストリームとして追加できます。OpenTok セッション内の 他のストリームからの音声はミックスされ、SIP エンドポイントに送信されます。 SIP通話にビデオが含まれている場合、他の参加者のストリームからのビデオ（最大9つ）は グリッドレイアウトで配置され、単一のビデオストリームとしてSIPエンドポイントに送信されます。

SIP相互接続機能は、ルーティングされたセッション（ OpenTok メディアルーター).

このページには以下のセクションがあります：

• SIP入門
• SIPコールの開始
• SIPコールの終了
• DTMF信号の送信
• 通話進行状況のモニタリング
• セキュリティへの配慮
• 技術的詳細
• 利用例
• よくあるご質問
• 既知の問題

SIP入門

OpenTok SIP Interconnect は、WebRTC エンドポイントと既存の電話システム間の相互運用性を実現し、ユーザーがウェブサイトやモバイルアプリケーションを閲覧しながら、そのコンテキスト内で SIP ベースの通話を行うことを可能にします。

対象ユースケース

コンタクトセンターの使用例

• 企業顧客は、コミュニケーションのオムニチャネル戦略の一環として、エンドユーザーが利用できるWebRTCに注目している：

  • よりユビキタスでコンテクスチュアルな体験を提供するために、電話だけでなく、ブラウザやモバイルアプリケーションを使用してコンタクトセンターと接続する。

  • 音声だけでなく、ビデオやコラボレーションを活用することで、効率性を向上させ、顧客満足度と顧客維持率を高める。

PSTNフォールバック

• 通常のOpenTokクライアントを使用した接続ができない場合があります：

  • 参加者の1人がWebRTCをサポートしていないブラウザを使用している場合、または
  • ファイアウォールの制限が厳しすぎる場合

• 上記の理由によりIP/OpenTok経由の接続に失敗した場合、お客様には代替手段が必要となります。OpenTok SIP Interconnectを利用することで、OpenTokセッション内で通常の電話をかけることが可能になります。この機能を利用するには、SIP-PSTNゲートウェイを設定する必要があります。

SIPコールの開始

SIP通話を開始するには、OpenTok REST API を使用します。以下の URL に対して HTTPS POST リクエストを送信してください：

https://api.opentok.com/v2/project/:apiKey/dial

交換 apiKey OpenTok APIキーを指定してください。

を設定する。 Content-Type ヘッダを application/json. カスタムを設定する X-OPENTOK-AUTH ヘッダー OpenTok REST API 呼び出しで使用可能な有効な JSON Web トークン。以下のセクションを参照してください。 OpenTok REST API 呼び出しの認証.

リクエストのボディに以下の形式のJSONデータを設定する：

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false,
    "video": true|false,
    "observeForceMute": true|false,
    "streams": ["stream-id-1", "stream-id-2"]
  }
}

JSONオブジェクトには以下のプロパティが含まれる：

• sessionId​ (必須) — 参加するSIP通話のOpenTokセッションID。

• token​ (必須) — 呼び出し先の参加者に使用する OpenTok トークン。 トークンを追加できます data 参加者がSIPエンドポイントであるかどうかを特定するため、あるいは電話番号などの その他の識別データを確認するためです。（OpenTokクライアントライブラリには、 セッションに接続しているクライアントの接続データを検査するためのプロパティが含まれています。）詳細は、 トークン作成 開発者ガイド

• シップ uri ​（必須）：OpenTokからお客様のSIPプラットフォームに向けて発信されるSIP通話の宛先として使用されるSIP URI。

  もしSIP uri を含む。 transport=tls ヘッダーを設定することで、Vonageと SIPエンドポイント間のネゴシエーションは安全に行われます。なお、これはネゴシエーション そのものにのみ適用され、音声の伝送には適用されません。音声 （および含まれる場合は動画）のメディア伝送も暗号化したい場合は、 secure プロパティ true.

  これは安全なコール・ネゴシエーションの例である：

  コピー

  "sip:user@sip.partner.com;transport=tls"
  

  これは、安全でないコール・ネゴシエーションの例である：

  コピー

  "sip:user@sip.partner.com"
  

  を設定することもできます。 transport ヘッダを transport=tcp または transport=udp. デフォルトのトランスポートは udp.

• シップ from (オプション)：(オプション): 発信者として最終的なSIP番号に送られる番号または文字列。 (オプション): 発信者として最終的なSIP番号に送られる番号または文字列。の形式の文字列でなければならない。 from@example.comここで from は文字列 または Numbers である。

  もし from には数字がセットされる（例えば、 "14155550101@example.com")、その番号は PSTN電話では着信番号として表示されます。もし from が未定義または文字列 (に設定される（例えば "joe@example.com")、PSTN電話では+000000が着信番号として表示されます。

  もし from が未定義であるか、あるいは文字列（たとえば "joe@example.com")、つまり 認識されない番号や許可されていない番号の場合、ほとんどの場合、それは "Unknown" リクエストがSIPプロバイダーによってPSTNターミネーションのためにキャリア に転送(forward)される前に。 プロバイダによって異なる、 "Unknown" は、PSTN電話では着信番号として表示されます。 場合によっては、プロバイダーは、番号詐称のような問題を避けるため、セキュリティ上の理由から、そのような着信を拒否することがある。 番号スプーフィングなどの問題を避けるためである。プロバイダーによって着信拒否されない場合、 +000000はPSTN電話の着信番号として表示されます。

  番号がE.164でない場合、またはE.164でない場合、その番号は未認識とみなされます。 Vonageバーチャル番号 に接続する場合 に接続する場合は Vonage Voice API, 例えば

• シップ headers​ (オプション) - このオブジェクトは、SIPヘッダーに追加されるカスタムヘッダーを定義する。 INVITE リクエストが OpenTok から SIP プラットフォームに送信されます。

• シップ auth (オプション) - このオブジェクトには username そして password で使用される SIP INVITE HTTPダイジェスト認証がSIPプラットフォームで要求される場合、HTTPダイジェ スト認証のリクエストを作成する。

• secure (オプション) - メディアを送信しなければならないかどうかを示すブール値のフラグ。 暗号化された (true)または(falseデフォルト）。

• video (オプション) — SIP通話にビデオが含まれるかどうかを示すブール値のフラグ (true)または(false（デフォルト設定）。ビデオが含まれている場合、SIPクライアントのビデオは、 OpenTokセッションに送信されるOpenTokストリームに含まれます。 SIPビデオは、480p、800 kbpsに制限されます。SIPクライアントは、OpenTokセッション内で公開されたストリームを動的に 合成したビデオストリームを受信します。

• observeForceMute (オプション) — SIPエンドポイントがこれを遵守するかどうかを示すブール値のフラグ 強制ミュート (true)または(false（デフォルト設定）。 また、 observeForceMute に設定する。 true、発信者は「*6」を押すことで、配信中の音声のミュートを解除または有効にすることができます。 「*6」によるミュート切り替えが機能するためには、SIP発信者がRFC2833 DTMF（RFC2833/RFC4733の数字）のネゴシエーションを行う必要があります。 SIP INFO またはインバンド DTMF では、ミュート切り替えはサポートされていません。発信者がミュートやミュート解除を行った場合、または強制ミュート操作によって SIP クライアントがミュートされた場合、発信者に対してメッセージ（英語）が再生されます。

• streams (オプション) - SIP呼に含めるストリームのストリームIDの配列。 の配列。このプロパティを設定しない場合、セッションのすべてのストリームが呼に 含まれる。 呼に含まれる。

呼び出しが成功すると、HTTP 200 レスポンスが返され、JSON レスポンスデータには接続 ID とストリーム ID が 含まれます：

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
  "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

JSONオブジェクトには以下のプロパティが含まれる：

• id - SIPコールの一意のID。

• connectionId — OpenTok セッション内の SIP 通話の接続に対する OpenTok 接続 ID。 この接続 ID を使用すると、OpenTok REST API を利用して SIP 通話を終了させることができます。 詳しくは、 次節.

• streamId — OpenTok セッション内の SIP 通話のストリームに対応する OpenTok ストリーム ID。

OpenTok SIPゲートウェイは、標準のSIPを INVITE REST呼び出しで指定したアドレスへ。 SIPエンドポイントが接続すると、そのエンドポイントはOpenTokセッションへの新しい「接続」として追加され、その 音声（およびビデオが含まれている場合はビデオ）は、OpenTokセッション内の新しいストリームに追加されます。 新しい接続は、 SIPエンドポイントが着信を受け取るか、または通話を受け入れるのを待つことなく、直ちにOpenTokセッションに追加されます。 セッションに 接続されているクライアントでは、OpenTok Client SDKが、新しい接続 およびストリームを示すイベントをディスパッチします（他のOpenTok接続やストリームの場合と同様です）。クライアントは、 セッション内の他のストリームを購読する場合と同様に、このストリームを購読することができます。

SIPコールの終了

SIPサーバーが BYE メッセージ（通話を終了するため）。また、 OpenTok REST API メソッドを使用して通話を終了することもできます。 クライアントをセッションから切断する. このメソッドを呼び出す際は、 SIP通話の接続IDを使用してください。（RESTメソッドについては SIP通話の開始 （応答データの一部として 接続IDを返します。）

SIP通話が終了すると、そのSIP通話に関連するOpenTokの接続およびストリームも終了します。 セッションに接続している各クライアントにおいて、OpenTokのクライアント側SDKは、 接続およびストリームが終了したことを示すイベントをディスパッチします（他のクライアントがセッションから切断された場合と同様です）。

OpenTok SIPゲートウェイは、5分間操作がない場合（5分間メディアの受信がない場合）、自動的に通話を終了します。 また、セキュリティ対策として、OpenTok SIPゲートウェイは、6時間以上継続するSIP通話をすべて終了します。

DTMF信号の送信

REST API を使用して、SIP エンドポイントに DTMF（デュアルトーン多周波数）信号を送信することができます。詳しくは、 SIPクライアントへのDTMF桁の送信.

テレフォニーイベントはSDPを介してネゴシエーションされ、RFC4733/RFC2833形式のデータとして リモートエンドポイントに送信されます。

通話進行状況のモニタリング

アプリサーバーでSIPコールのリアルタイムイベントコールバックを受信するために登録します。

開発者は、OpenTok REST API を使用して、自社の SIP プラットフォームを OpenTok セッションに接続することができます。これにより、SIP 通話からの音声（および、含まれている場合は動画）を、OpenTok セッション内のストリームとして追加することが可能になります。 SIP通話モニタリング機能により、開発者はアプリサーバー内からSIP通話の進行状況を監視できます。コールバックを登録することで、指定したコールバックURLに、SIP通話の進行状況に関する情報が含まれたHTTP POSTリクエストが送信されます。

コールバックの登録

SIP通話のイベント情報は、サーバー内のHTTPエンドポイントに登録することができます。 登録されたアクティビティが発生するたびに、OpenTokインフラストラクチャから お客様のエンドポイントに対してHTTPリクエストが送信されます。

コールバックURLを登録する：

1. あなたのところへ Vonage Video API アカウントページ.

2. コールバックを登録したい OpenTok プロジェクトを選択してください。

3. SIP MonitoringセクションでコールバックURLを設定する。

   安全なコールバック： ウェブフック・コールバック・リクエストを署名付きコールバックで保護することができます、 署名の秘密を使って参照 安全なコールバック.

SIPコールアクティビティの監視

正しく登録されると、OpenTokのインフラストラクチャは、特定のプロジェクトにおける すべてのSIPコールに対してHTTPリクエストを送信します。これは、SIPコールの進行状況を 追跡したり、エラーが発生した場合に適切な措置を講じたりするのに役立ちます。以下の動作が予想されます：

• 少なくとも1つ callCreated イベント・パー・コール

• 少なくとも1つ callDestroyed イベント・パー・コール

• 未定義の数 callUpdated イベント/コール

• 未定義の数 muteForced イベント/コール

コール・クリエイト

エンドポイントは、作成されたSIPコールごとに以下のJSONを受け取る：

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456", 
  "event":  "callCreated",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

参照 JSONプロパティ を参照されたい。

更新された電話

各SIPコールの状態が更新されると、エンドポイントは以下のJSONを受信する：

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callUpdated",
  "state":  "HANGUP",
  "timestamp":  1470257688309,
  "call": {
     "id":  "<conference-id>",
     "connectionId":  "<sip-ot-connection-id>",
     "createdAt":  1470257688143
  }
}

参照 JSONプロパティ を参照されたい。

破壊されたコール

エンドポイントは、各SIPコールが終了するときに、以下のJSONを受信する：

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "callDestroyed",
  "reason_code":  "400",
  "reason_message":  "Bad Request",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

参照 JSONプロパティ を参照されたい。

ミュート強制

SIP通話がミュートされた場合、エンドポイントには以下のJSONが受信されます。 a 強制ミュートによるモデレーションイベント:

{
  "sessionId":  "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId":  "123456",
  "event":  "muteForced",
  "timestamp":  1470257688309,
  "call": {
    "id":  "<conference-id>",
    "connectionId":  "<sip-ot-connection-id>",
    "createdAt":  1470257688143
  }
}

参照 JSONプロパティ を参照されたい。

を設定しなければならないことに注意してください。 observeForceMute オプション true) SIP 接続を確立する際、強制ミュートによるモデレーションイベントを検知できるようにするため。

SIPモニタリング・イベントのJSONプロパティ

JSONオブジェクトには以下のプロパティが含まれる：

• sessionId -- このイベントに関連付けられたセッションID

• projectId -- このイベントに関連するプロジェクト ID

• event -- callCreated | callUpdated | callDestroyed | muteForced

• reason_code -- に対して callDestroyed イベントを開催する、 reason_code は以下のいずれかに設定されている：

  • A 標準SIPレスポンスコード SIPハンドシェイクにおけるエラーを捕捉するため

  • 700 -- 「通常の切断」 -- この原因は、通話に関与しているユーザーのいずれかが通話の切断を要求したため、 通話が切断されていることを示しています。

  • 703 -- "Unexpected Clearing" (予期しないクリア) -- この原因は、呼が予期せずクリアされたことを示す。

  • 704 -- 「メディアタイムアウト」 -- このコードは、当社のSIPブリッジが、 相手側のSIPエンドポイントからRTPトラフィックを一切受信できなかったことを示しています。

  • 705 -- "Max Duration" -- 通話が最大継続時間に達した。

  • 706 -- "Max Inactive" -- 呼が最大の非アクティブ時間に達した。

• reason_message -- に対して callDestroyed イベントを開催する、 reason_message は、 呼び出しが破棄された理由を説明する文字列です。

• state -- に対して callUpdated イベントを開催する、 state は以下のいずれかに設定されている：

  • DIALING -- SIPコールが開始された

  • RINGING -- SIPコールは現在呼び出し中です

  • ON_HOLD -- SIPコールは保留中です

  • ACTIVE -- SIPコールが応答され、現在進行中である。

  • HANGUP -- 完了したSIPコール

• timestamp -- イベントのタイムスタンプ。Unixのエポックからのミリ秒単位。

• call -- 以下のプロパティを含む、接続を定義するオブジェクト：

  • id -- カンファレンスID

  • connectionId -- SIPクライアントのコネクションID

  • createdAt —- 呼び出しが作成された時点のタイムスタンプ値（Unixエポックからの経過時間、ミリ秒単位） —-

セキュリティへの配慮

SIPサーバーでSIPインターフェースを使用する際、Vonageが推奨するベストプラクティスがいくつかあります。 これらは、サーバーで受信したSIPコールが正当なものかどうかを認証・認可する仕組みを提供し、 すべてのシグナリングおよびメディアを暗号化することで、 起こりうる攻撃を軽減することを目的としています：

• 通信の傍受を防ぐため、TLS を使用し、シグナリングにはセキュアコール（SRTP）を有効にしてください。

• サーバーでSIP認証を有効にしてください。そうしないと、SIP URIを知っている人なら誰でも サーバーに発信できるようになってしまいます。

お問い合わせ その他ご質問があれば

技術的詳細

RFC3550（RTP/RTCP）のサポート： メディアトラフィックは、暗号化（SRTP）または非暗号化 （プレーンRTP）のいずれかとなります。暗号化の場合、DTLSおよびSDESプロトコルの両方がサポートされています。

コーデック対応： OpenTok SIPゲートウェイは、OPUS、G.711、G.722の音声コーデック、 およびH.264、VP8の動画コーデックに対応しています。SIPビデオの解像度は480p、ビットレートは800 kbpsに制限されています。

シグナリング： OpenTok SIPゲートウェイは、UDP、TCP、およびTLS上のRFC 3261（SIP）に対応しています。 特定の拡張機能に関する情報やサポートが必要な場合は、Vonageまでお問い合わせください。

OpenTok SIPゲートウェイは、OpenTok SIPゲートウェイによって開始されたSIPダイアログの一部でない限り、 サードパーティのSIPプラットフォームから送信されるSIPメッセージをすべて拒否します。 OpenTok SIPゲートウェイで開始された通話は、以下のいずれかを使用して保留にすることができます。 re-­INVITE ～とともに sendonly/inactive SDPまたは re-­INVITE をポート0としてSDPに含める。

その他の考慮事項 アーリーメディアは無効。

利用例

NodeおよびPHP用のOpenTokサーバーSDKには、OpenTok SIP 相互接続機能を使用したOpenTok Dial APIの呼び出し例が含まれています。例については、以下をご覧ください：

• https://github.com/opentok/opentok-node/tree/master/sample/SipInterconnect
• https://github.com/opentok/OpenTok-PHP-SDK/tree/master/sample/SipCall

以下に、OpenTok SIP InterconnectとNexmoを利用したSIP連携のサンプルをご紹介します：

• 発信
• 電話会議

よくあるご質問

SIPとは？なぜSIPが重要なのですか？

セッション開始プロトコル(Session Initiation Protocol: SIP)は、マルチメディア通信セッションのシグナリングと制御のための通信プロトコルである。SIPの最も一般的なアプリケーションは、インターネットプロトコル（IP）ネットワークを介した音声通話やビデオ通話、インスタントメッセージングなどのインターネット電話である。

当社の場合、これはOpenTokセッションからサードパーティのSIPサーバーへの通話を確立するために使用されます。通話が確立されると、音声（および、含まれている場合は映像）はRTPプロトコルを使用して送信されます。

SIPとPSTNの違いは何ですか？OpenTokはPSTNゲートウェイを提供していますか？

PSTNは伝統的な電話ネットワークである。PSTNはIPネットワークではないのでSIPは使わないが、Nexmoのような多くのプロバイダーはSIPプロトコルをPSTNプロトコルに変換するゲートウェイを持っている。そうすることで、IP経由のSIP通話が電話通話に変換されます。

実際には、Vonage Video APIがPSTN通話をサポートしていなくても、SIP通話をサポートすることでこれを実現できます。あとは、SIP通話をPSTN通話に変換してくれるプロバイダーを見つけるだけです。

OpenTokのSIP相互接続機能を使って、通常の電話にかけることはできますか？

OpenTok SIP Interconnect を利用すると、パートナーは任意の SIP エンドポイントへの通話を発信できます。通常の電話機との間で通話を行うには、顧客側で SIP 通話を携帯電話網や固定電話網で使用されるプロトコルに変換するためのゲートウェイが必要となります。

通常の電話番号（PSTN）からのダイヤル発信やダイヤル着信を処理する方法はありますか？

OpenTok SIP Interconnect を利用すれば、お客様は OpenTok セッションから任意の SIP 宛先へ発信することができます。さらに、SIP ゲートウェイ（自社製またはサードパーティ製）を設定することで、通常の電話番号へ発信することも可能です。

SIP相互接続APIは着信SIPコールをサポートしていませんが、お客様はSIPゲートウェイ（自社製またはサードパーティ製）を使用して、通常の電話（PSTN）からの着信とOpenTokからの発信SIPコールをブリッジすることで、通常の電話からの発信機能を実装することができます。 会議のユースケースを実演するサンプルアプリケーションは、以下からご覧いただけます。 これ.

OpenTok SIP Interconnect は動画の送信に対応していますか？

はい。 video フラグ true SIP通話を開始する際 以下の方法を使用して REST APIメソッド. SIPビデオは 800 kbpsで480pに制限されています。

WebRTCエンドポイントとSIPエンドポイントでは、知覚される音質に顕著な違いがありますか？

期待されるのは、SIPエンドポイントでの待ち時間は増えるものの、同じ品質であることだ。

OpenTok SIP Interconnect では、アーカイブ機能はどのように動作するのでしょうか？

アーカイブ機能は、WebRTCセッションにおいて現在とまったく同じように動作します。最大16のビデオストリーム および最初の50のオーディオストリーム（SIPオーディオおよびビデオストリームを含む）がアーカイブの対象となります。

ユーザーはIVRをどのように操作するのですか？ウェブ/モバイルアプリにダイヤルパッドはありますか？

REST API を使用すると、SIP クライアントに DTMF 信号を送信し、対話型音声応答 （IVR）システムに対応させることができます。詳しくは、 DTMF信号の送信.

OpenTok SIP Interconnect は、どのような SIP サーバーと互換性がありますか？

最も一般的な通信機器（ACME packet、Broadsoft）、一般的なSIPプラットフォーム（Nexmo、その他）、最も一般的なオープンソースSIPサーバー（freeswitch）との相互運用性をテストしました。すべてのSIPサーバーとの相互運用性を保証することは不可能ですが、失敗の可能性を減らすために、SIP拡張/機能の使用を制限するようにしています。これまでのところ、新しいSIPサーバーと相互運用するために私たちのソリューションを変更する必要はありませんでした。

OpenTokセッションに接続されているSIPクライアントへの通話を、どのように切断すればよいでしょうか？

• 既存のクライアントAPIの使用 — OpenTokセッションに接続し、モデレーター権限を持つWeb（JavaScript）クライアントは、SIPクライアントを含む他のクライアントに対して、セッションからの切断を強制することができます。

• を使用している。 サーバーサイドのモデレーション用 REST API — WebRTCクライアントがモバイル端末である場合、または顧客がクライアントにモデレーター権限を付与したくない場合、アプリケーションサーバーは接続中のクライアントに対してHTTP DELETEリクエストを発行し、サーバー側から強制的に接続を切断させることができます。

既知の問題

Linphone SIPクライアントに対してSIPビデオ通話が発信され、そのビデオ通話がVP8コーデックでネゴシエーションされた場合、 LinphoneからOpenTok SIPゲートウェイへの着信ビデオが、黒いフレームとして表示されます。