コール

コールは、開発者向けに設計された音声機能で、 API (opens in a new tab) 経由でのみ利用できます。

コール機能を使用すると、インバウンドコールとアウトバウンドコールを処理するアプリケーションを作成できます。作成したアプリケーションは、音声シナリオロジックを実装し、コールAPIを使って、選択した音声チャネル (PSTN、webRTC、SIP) を介してコールやカンファレンスの間に発生するアクションを制御したり、実行したりします。

アプリケーションは、電話番号マスキング、Click-to-Call、音声メッセージやIVRと違って、特定のユースケースシナリオに縛られることはありません。コールAPIがビルディングブロックとなり、ほぼ何でも構築しやすくします。

コールAPIで次のいずれかの機能を使用するには、アカウントでこれらの機能を有効にする必要があります。

• レコーディング
• 自動機械検出 (AMD)
• カンファレンス
• メディアストリーミング
• SIPトランキング

担当のアカウントマネージャーに連絡して、これらの機能を有効にしてください。

コンセプト

コール機能には、次の4つの主要な概念があります：

• コール構成
• 番号
• コールAPI
• イベント

コール構成

このセクションでは、コールAPIを使用するアプリケーションのコール構成を作成するプロセスについて説明します。この構成は、プラットフォームが提供する多様なAPIメソッドとイベントを統合する上で重要な部分を占めます。

コール構成の作成

コール構成は、コールAPIメソッドを使用するアプリケーションに必要な宣言です。これには、一意の識別子である callsConfigurationId が含まれます。このIDは、作成時に開発者が指定するか、指定しない場合はシステムによって生成されます。開発者は、コール構成の管理が容易になるよう、それぞれのコール構成にわかりやすい名前を割り当てるオプションもあります。コール構成を作成するには、まずコールAPI用に アプリケーションを宣言 (opens in a new tab) します。特定のIDが頭に浮かんでいる場合は、それを指定します。それ以外の場合は、システムによって自動的に割り当てられます。わかりやすい名前を追加することもお勧めしますが、これは任意です。

イベントサブスクリプションの関連付け

新しいコール構成には、それぞれ関連付けられたイベントサブスクリプションが必要です。このサブスクリプションは、アプリケーションがコールAPIから受け取る イベントの概要を示します。イベントの選択は、アプリケーションがAPIとの間でどのようなやり取りをするかを決める非常に重要なステップです。このセクションでは、イベントサブスクリプションを作成し、それをコール構成に関連付ける手順について説明します。

• Create a subscription (サブスクリプションの作成)：この手順の最初のステップは、少なくとも1つのイベントサブスクリプションを作成することです。サブスクリプションの作成や管理は、NTT CPaaSのWebインターフェイス上でまたはAPIを通じて行うことができます。
  1. Specify the channel type (チャネルの種類の特定)： イベントサブスクリプションを設定する際、チャネルの種類をVOICE_VIDEOとして指定します。これにより、アプリケーションが処理するイベントの性質が定義されます。
  2. Define the profile (プロファイルの定義)： サブスクリプションのプロファイルセクションには、アプリケーションのウェブフックの詳細を含める必要があります。これにはウェブフックのURLとセキュリティ仕様が含まれ、それにより、セキュアで目的に合致した通信が保証されます。
  3. List the desired events (希望するイベントの一覧表示)： サブスクリプションの events 配列で、ウェブフックに送信するすべての コールAPIイベントを一覧表示します。これらは、アプリケーションの機能に関連するすべてのイベントを含むコンマ区切りのリストとして指定する必要があります。考えられるすべてのコールAPIイベントの一覧は、 Event Webhook (イベントウェブフック) (opens in a new tab) で確認できます。
  4. Criteria object configuration (基準オブジェクト構成)： 最後のステップは、サブスクリプションのcriteriaオブジェクトでcallsConfigurationIdを指定することです。これにより、イベントサブスクリプションがコール構成に直接リンクされ、適切なイベントがアプリケーションにルーティングされます。

イベントの処理方法を整理するために、同じ callsConfigurationId 基準を使用する複数のサブスクリプションを定義できます。この方法により、異なるイベントタイプを別々のウェブフックにルーティングすることができ、構造と処理効率が向上します。その際、各サブスクリプションには、その callsConfigurationId に対して一意のイベントタイプのセットが含まれていることをご確認ください。

番号

インバウンド音声シナリオでは、アプリケーションがインバウンドコールへの応答またはルーティングを行えるようになるために、アカウントに少なくとも1つのNTT CPaaS音声番号を持たせる必要があります。NTT CPaaS がこれらのインバウンドコールに関連するイベントをルーティングする先を認識できるように、この番号をアプリケーションに紐づける必要があります。

NTT CPaaS の音声番号は1つのアプリケーションにしか関連付けられませんが、同じアプリケーションに複数の電話番号を紐づけることはできます。

アウトバウンド音声シナリオでは、アプリケーションがPSTN、webRTCまたはSIPの呼び出し先へのコールを開始できるようになるために、アカウントに少なくとも1つのNTT CPaaS音声番号を持たせる必要があります。

この番号は、アプリケーションに新しいアウトバウンドコールの発信者IDとして指定できます。この番号はアプリケーションに紐づける必要はなく、同じ番号を異なるアプリケーションによって生成されるアウトバウンドコールの発信者IDとして表示させることもできます。

使用可能な音声番号は、 API (opens in a new tab) と Webインターフェイス (opens in a new tab)の両方で検索してリースできます。

NTT CPaaS 音声番号をアプリケーションに紐づけるには、API (opens in a new tab)でFORWARD_TO_SUBSCRIPTIONアクションとcallsConfigurationIdを指定する必要があります。

コールAPI

アプリケーションがコールやカンファレンス内で実行する必要があるアクションは、RESTAPIを介して実行されます。APIは、HTTPステータスコードとペイロードで同期的に応答し、リクエストしたアクションの受信を確認します。

下記に示すいくつかの 利用方法 (opens in a new tab) があります：

• コールの作成とコールの詳細の取得
• カンファレンスの作成とカンファレンスの詳細の取得
• コールやカンファレンスでのアクションの実行
• オーディオファイルとレコーディングの管理

イベント

コールAPIを使ってコールやカンファレンスで実行するほとんどのアクションは、アクションの実行完了確認またはエラー発生通知のイベントを、アプリケーションにトリガーします。アプリケーションに新しいインバウンドコールが届く時も、そのコールに関するすべての情報 (TO、FROM など) を含むイベントがアプリケーションに送信されます。

次の図を見ると、クライアントのアプリケーションまたはプラットフォームで2つの異なるウェブフックが使われていることが分かります。1つは CALL_RECEIVEDイベントのみを受信し、もう1つは他のすべてのイベントタイプを受信しています。

コールAPIについて

コール、カンファレンスとダイアログ

NTT CPaaS プラットフォームのすべてのインバウンド接続 (TO) またはアウトバウンド接続 (FROM) は、それぞれコールレッグとして指定されます。

このドキュメントの残りの部分ならびにAPIドキュメントでは、コールレッグのことをコールと呼ぶことがあります。

音声または動画アプリケーションは常に、少なくとも1つのコールを処理します。例えば：

• ユーザーを呼び出して音声メッセージを配信する音声メッセージング用アプリケーションは、アウトバウンドコールを作成します。
• 対話型音声応答アプリケーションは、インバウンドコールに応答します。
• 2人以上の参加者が互いに会話できるアプリケーションは、インバウンド、アウトバウンド、混合のいずれであっても、2つ以上のコールを処理します。

コールは複数の方法で接続 (ブリッジ) できます：

1. カンファレンス：
   • これらの カンファレンスメソッド (opens in a new tab)で明示される手順により、カンファレンスを作成したり、参加者を追加または削除したりできます。
   • カンファレンスを使用すると、カンファレンスのステータスと各参加者のステータスに関連するイベントが多数発生する可能性があります。
   • カンファレンスの参加者数は、関係するエンドポイントの種類を問わず、最大 15人に制限されています。
   • カンファレンスは、2つ以上のコールレッグまたは参加者を接続することが予想される場合または参加者をその場で追加および削除する予定がある場合に使用するのに適しています。
2. 接続：
   • 接続メソッド (opens in a new tab)を使用すると、カンファレンスオブジェクトを明示的に操作することなく、カンファレンスの2つのコールレッグをすばやく結びつけることができます。
   • 接続メソッドを使用すると、カンファレンスが暗黙的に作成されますが、全体的な実装が簡略化されます。
   • 暗黙的なカンファレンスは 2つのコールを接続する時に作成されます。カンファレンスが作成されると、いつでもカンファレンスの参加者を追加または削除する操作が可能になります。
3. ダイアログ：
   • ダイアログを使用すると、2つのコールをブリッジできます。ブリッジ可能なコール数は2つに限られています。
   • ダイアログはコールをブリッジするために使用します。カンファレンスとは別のオブジェクトです。
   • ダイアログで接続された 2つのコールに、追加の参加者に加えることはできません。ダイアログの一部であるコールを、別のダイアログに移動させることはできません。
   • ダイアログのフロー全体で発生するイベントの数は、接続またはカンファレンスのメソッドを使用する場合よりもはるかに少ないです。
   • ダイアログは、2つのコールレッグ (または参加者) のみを結びつける必要があるシナリオの場合に使用することをお勧めします。

ダイアログと接続／カンファレンスには他にも違いがあります。その主なものは次のとおりです：

• 初期メディア伝搬： 新しいPHONEコールを既存のコールに接続すると、呼び出し先のネットワークは、発信者にコールの進行状況を通知する帯域内トーンまたはアナウンスを発する場合があります。ダイアログを使用してコールを接続する場合、そのような初期のメディアがあれば、参加者間に伝搬されます。
• メディアバイパス： PHONE/PSTN 経由で2つのコールを接続し、両方のコールで同じコーデックが使用されている場合、NTT CPaaSプラットフォームはコールのシグナリング部分のみを処理しますが、メディア (RTP) は接続されたエンドポイント間を直接流れるため、メディアはエンドポイント間の最短パスを最小限の遅延で通過します。RTPフローは、ダイアログのレコーディングまたはDTMF収集などのアクションがリクエストされた場合に、NTT CPaaSプラットフォームによって再キャプチャーされますので、ご注意ください。同様に、ダイアログが録音されている時にそのレコーディングが停止された場合、NTT CPaaSプラットフォームは RTPメディアを解放し、メディアバイパスに切り替わります。
• インバウンドコールへの応答： ダイアログを使用するシナリオで、ダイアログの使用時にインバウンドコールを新しいアウトバウンドコールにブリッジする場合、アプリケーションは、接続やカンファレンスの場合のように、インバウンドコールに明示的に応答する必要はありません。ダイアログを使用する場合、新しいアウトバウンドコールに応答すると、NTT CPaaSプラットフォームは自動的にインバウンドコールに応答し、その2つのコールをブリッジします。
• コールレッグでのアクション：コールレッグがダイアログを使用して結合されている場合、ダイアログオブジェクト自体でのみメディア (オーディオファイルまたは音声合成) を再生できるため、このオーディオはダイアログの一部である 2つのコールレッグによって聞こえます。カンファレンスに参加しているコールレッグでは、カンファレンス内の特定のコールレッグに対して音声ファイルやText-to-Speechの再生など、個々のコールメソッドを使用でき、そのコールレッグだけで再生メディアを聞けるようにできます。

すべてのコールには独自の一意の callId があります。すべてのカンファレンスまたはダイアログには、独自の一意のconferenceId または dialogId があります。これらの識別子は互換性がありません。

これを念頭に置いて、コールをブリッジする方法としてユースケース別に推奨されるメソッドを次に示します。

• インバウンドコールをアウトバウンドコールの呼び出し先にブリッジ (「コール転送」) する必要がある場合：ダイアログが最適です
• 2つのアウトバウンドコールをブリッジする必要がある場合：ダイアログが最適です
• 2人以上の参加者をブリッジする必要がある場合： カンファレンスまたは接続メソッドを使用します
• 「保留中」の状況に対応する必要がある場合：カンファレンスメソッドを使って「保留中」の参加者を
  • カンファレンスから一時的に削除できます。
  • メディアは、保留時間中に参加者のコールレッグで再生されます。
  • コールが再開されると、参加者のコールレッグは別の参加者とのカンファレンスに戻されます。
• 「スマートダイヤラー」のユースケースを実装するには、カンファレンスまたは接続メソッドを使用します。
  • エージェントがカンファレンスに接続されます。
  • 接続されたアウトバウンドコールは、そのカンファレンスでエージェントに接続されます。

コールの状態

次のセクションでは、各コール状態の図を示し、それぞれの詳細について説明します。

アウトバウンドコールの状態

次の図は、アウトバウンドコールの様々な状態と、これらの状態遷移を表すイベントを示しています。

PRE_ESTABLISHED や RINGING などの初期のダイアログ状態は、それぞれのイベント(オプションまたは任意の順序で表示される)を含め、通信事業者の実装によって異なります。WebRTCとSIPへのコールは、PRE_ESTABLISHED状態を経由しません。

アウトバウンドコールは、常に次のいずれかの最終コール状態になります。

こうしたコールの最終ステータスについては、先行する CALL_FINISHED または CALL_FAILED イベントに、コールが終話または失敗に終わった理由が含まれます。

インバウンドコールの状態

次の図は、インバウンドコールの様々なステータスならびにこれらのステータスの遷移を表すイベントを示しています。

インバウンドコールは、常に次のいずれかの最終ステータスで終了します：

こうしたコールの最終ステータスについては、先行する CALL_FINISHED または CALL_FAILED イベントに、コールが終話または失敗に終わった理由が含まれます。

参加者の状態

マルチパーティコール (1対1または実際のカンファレンス) を処理する際、アプリケーションは参加者の状態を適切に追跡するために複数のイベントをサブスクライブできます：

• PARTICIPANT_JOINING、PARTICIPANT_JOINED、PARTICIPANT_JOINED_FAILED、PARTICIPANT_REMOVED - 各名称が示すように、これらのイベントは、カンファレンスへの参加者の参加状態をアプリケーションに通知します。
• PARTICIPANT_MEDIA_CHANGEは、カメラや画面共有のオン/オフ(WebRTCエンドポイント)、マイクのオン/オフ(WebRTCエンドポイント)、参加者の明示的なミュート(解除)など、参加者のメディアセッションの内容が変わった時にその変更をアプリケーションに通知します。
• PARTICIPANT_STARTED_TALKING および PARTICIPANT_STOPPED_TALKING - これらのイベントは、conferenceId および callId で識別される参加者がコールを開始または停止した時にその状態をアプリケーションに通知します。

エンドポイント

コールまたはカンファレンスを作成する時は、呼び出し先のエンドポイントまたはエンドポイントのリストを指定する必要があります。

NTT CPaaSプラットフォームは、次のタイプのエンドポイントに対応しています：

1. PHONE： PHONEエンドポイントタイプは、常に E.164 (opens in a new tab) 形式のphoneNumber に関連付けられます。E.164 形式の番号には、先頭に「+」や「00」が含まれませんのでご注意ください。
2. WebRTC： WebRTCエンドポイントタイプを使用する場合、少なくとも呼び出されるエンドユーザーを指定する一意の識別子 (identity*,*) を指定する必要があります。
3. SIP： アプリケーションは、セッション開始プロトコル (SIP) を使用すると、オフィスのPBX (オンプレミスまたはクラウド) に接続されているユーザーに通話できるようになります。SIPエンドポイントに通話できるようになるには、少なくとも username (ユーザー名)、*host (ホスト)とport (ポート)*を宣言する必要があります。SIPエンドポイントに向けて通話する場合、そのコールを作成する前に、コールAPIのSIPトランクメソッドを使用して、NTT CPaaS とオフィスのPBX間のSIPトランクを定義する必要があります。
4. VIBER：ViberユーザーからのインバウンドコールはVIBERタイプで、呼び出し元のViberユーザーのMSISDNが含まれます。Viberユーザーからのコールの受信に関する詳細については、Viber Business Calls について詳述しているドキュメントをご参照ください。

PHONEおよびSIPエンドポイントに通話する際、着信側に表示するcallerIDを指定できます。callerIDは、NTT CPaaSからリースする音声番号であることが理想的です。

WebRTCエンドポイントに向けて通話する場合、任意の英数字文字列を使ってfromDisplayNameを設定できます。

コールのフロー

インバウンドコールのフロー

アプリケーションがインバウンドコールに関するイベントを受信し、これらに応答できるようにするには、NTT CPaaSプラットフォーム上の着信番号にイベントを関連付ける必要があります。

NTT CPaaSのDID番号をアプリケーションに関連付けるには、DID番号で音声アクションをセットアップします。

• API経由：
  • NTT CPaaSの番号で、FORWARD_TO_SUBSCRIPTIONというアクションタイプを使用して音声セットアップ (opens in a new tab)を作成し、callsConfigurationIdを含めます。
• Webインターフェイス経由：
  • Numbersアプリケーション (opens in a new tab)に移動し、番号を選択します。
  • Voiceタブを選択します。
  • 転送アクションを Forward to subscription (サブスクリプションに転送) にしたインバウンド設定を作成し、callsConfigurationIdを指定します。

新しいコールを受信すると、アプリケーションはコールの識別番号 (callId) とtoおよび_from_電話番号を含むCALL_RECEIVED イベントを受け取ります。send-ringingメソッドを使用して明示的に送信しない限り、発信者には呼び出し音は聞こえません。次に、アプリケーションは独自のロジックに基づいて、コールを拒否するか、もしくはコールに事前応答または応答するかを決定できます。コールを受け入れることを決定した場合、アプリケーションはacceptメソッドを使用します。

CALL_ESTABLISHED イベントを受信すると、アプリケーションはNTT CPaaSプラットフォームからコールがライブになったことを確認し、次のステップに進むことができるようになります。

アプリケーションが CALL_FAILED または CALL_FINISHED イベントを受信すると、そのイベントのペイロードを検査して、コールのステータスならびにコールが終話または失敗に終わった原因に関する、より詳細な情報を取得します。

次の図を見ると、アプリケーションが コールAPIイベントを受信する際、 2つの異なるウェブフックが使われていることが分かります。

アウトバウンドコールのフロー

アプリケーションがNTT CPaaSプラットフォームに新しいアウトバウンドコールの作成をリクエストすると、呼び出されるエンドポイントのタイプ (PSTN、WebRTC、SIP) が指定されます。NTT CPaaSプラットフォームは、この新しいコールの識別子 (callId) を返し、そのcallId のステータスを持つイベントをアプリケーションのイベントウェブフックに送信します。

CALL_ESTABLISHED イベントを受信すると、アプリケーションはNTT CPaaSプラットフォームからコールがライブになったことを確認し、次のステップに進むことができるようになります。アプリケーションが CALL_FAILED または CALL_FINISHED イベントを受信すると、そのイベントのペイロードを点検し、コールのステータスやコールが終話または失敗に終わった原因に関する、より詳細な情報を取得します。

接続／カンファレンスを使った2つのコールの接続

エンドユーザーが互いに会話できるように複数のコールを接続するには、接続メソッドまたは カンファレンス関連のメソッドを使用します。接続メソッドを使用すると、既存の 2つのコールを接続したり、既存のコールを新しいコールに接続したりできます。これらのメソッドにはカンファレンス機能が暗黙的に使用されるため、開発者がカンファレンスオブジェクトを明示的に操作する必要がありません。

下記に示すコールのフロー図では、アプリケーションがまず一意の callId 識別子をそれぞれ付けた2つのコールを作成するところから始まります。2つのコールがそれぞれライブになっていることが確認できる両方のイベント(CALL_ESTABLISHED イベント)を受信した後、アプリケーションは接続メソッドを使ってコールを接続し、両コールの一意のcallIdをそれぞれ指定します。

そのリクエストを受信すると、NTT CPaaSプラットフォームは次のことを行います：

• 会議室を作成し、CONFERENCE_CREATED イベントで確認します。
• PARTICIPANT_JOINING イベントと PARTICIPANT_JOINED イベントで確認した情報に基づいて、指定した各コールを参加者として追加します。

イベントには常に、関連する callId と conferenceId への参照が含まれます。

開発者は、アプリケーションが CONFERENCE_CREATED、PARTICIPANT_JOINING およびPARTICIPANT_JOINING および PARTICIPANT_JOINED イベントの成立をすべて待つか、 PARTICIPANT_JOINED イベントの成立だけを待ってコールがブリッジされたことを確認するかを選択できます。

ダイアログを使った2つのコールの接続

2つのコールのみを接続する予定で、参加者の状態を操作 (参加者の追加／削除) できない場合は、上記で説明したようにダイアログメソッドを使用することをお勧めします。

次のシーケンス図で示すコールのフローは、アプリケーションがエンドユーザーAへのアウトバウンドコールを1つ作成するところから始まります。ダイアログは、2つのコールを接続する際、各コールを親コールと子コールに分けて処理します。ダイアログ上で2つのコールを接続する最も一般的な方法は次のとおりです：

• 既存の(確立された)コールを使用する場合は、それがインバウンドであるかアウトバウンドであるかに関わらず、これが親コールになります。
• ダイアログ作成リクエストで呼び出し先を指定する場合は、これが子コールになります。

シーケンス図に示されている例では、エンドユーザーAのコールがライブであることを確認するイベント (CALL_ESTABLISHED イベント) を受け取った後、アプリケーションはダイアログメソッドを使ってエンドユーザーAをエンドユーザーBに接続し、エンドユーザーAのコールのcallIdとエンドユーザーBに接続するエンドポイントデータを指定しています。この例からも分かるように、このシナリオでは、NTT CPaaSプラットフォームと顧客のアプリケーション間のイベントフローが簡素化されています。

既存の (確立された) 2つのコールに基づいてダイアログを作成する (opens in a new tab) メソッドも存在しますが、このメソッドは、親コールID (つまり、最初のコール) と等しい parentCallIdパラメーターであることを示す コール作成メソッド (opens in a new tab) を使って 2番目のコール (子コール) が作成された場合にのみ機能することを理解しておく必要があります。

カンファレンスのフロー

コールAPI経由のカンファレンスを使用すると、アプリケーションは同じ会議室に参加者を最大15 人追加できます。カンファレンスは複数のエンドポイントを同時にサポートするため、同じカンファレンスの参加者は電話 (PSTN)、WebRTC (ビデオ有りまたは無し) やSIPを介して参加できます。

カンファレンスに参加者を追加する方法は複数あります：

• 既存の(ライブ) コールをカンファレンスに移動できます。
• 新しいアウトバウンドコールを開始し、単一のAPI メソッドを使用して既存のカンファレンスにすぐに移動できます。

次のカンファレンスフローでは、既存のコールをカンファレンスに追加する際、エンドユーザーAとエンドユーザーBへのコールがすでにライブになっていることを前提としています。まずはカンファレンスは作成する必要があります。続いて、このカンファレンスが作成されたことが、一意の conferenceIdを含むCONFERENCE_CREATED イベントによって確認されます。参加者を呼び込むには、conferenceIdならびにエンドユーザーAとエンドユーザーBのそれぞれのコールの一意のcallId がいずれも必要になります。

最後の参加者がカンファレンスから退出すると、カンファレンスは自動的に終了します (CONFERENCE_FINISHED イベント)。終了したカンファレンスは再開できません。同じ名前で新しいカンファレンスを作成することもできますが、その同名のカンファレンスには新しい一意のconferenceIdが付与されることになります。

アプリケーション間のコールの転送

前述したように、コールは常にアプリケーションに属しているため、コールAPIプラットフォームは、そのコールのステータスまたはそのコールで実行したアクションに関連するイベントをどのウェブフックに送信するかを認識しています。コールAPIを使用すると、application transferメソッドを使って、コールのアプリケーション所有権を変更できます。

例えば、IVR シナリオを実装するアプリケーションと、自社で独自に開発したコールセンタープラットフォームを表すアプリケーションがあるとします。IVRアプリケーションへのインバウンドコールはIVRアプリケーションによって所有されますが、IVRシナリオでのエンドユーザーの選択に従って、そのコールをIVRからコールセンターに転送する必要があります。このシナリオでは、IVRアプリケーションは、コールセンターアプリケーションへそのコールのアプリケーションを転送することをリクエストします。

コールセンターアプリケーションは、この転送をリクエストするイベント(APPLICATION_TRANSFER_REQUESTED)として受信し、対応するAPIメソッドを使ってその転送を受け入れるか拒否します。リクエストを出しているアプリケーション (IVR) は、その最終ステータス (APPLICATION_TRANSFER_FAILEDまたはAPPLICATION_TRANSFER_FINISHED)を確認するイベントを受信します。

カンファレンスのロール

カンファレンス中に柔軟で安全なコミュニケーションフローを提供するために、コールAPIでは、参加者に特定のロールを割り当てる機能をサポートしています。カンファレンスでのそれぞれのロールによって、各参加者がカンファレンスを見たり、発言したり、聴取したりする権限の範囲が決まります。

カンファレンスの参加者に特定のロールを割り当てることで、セッションに参加している他のメンバーの体験を損なうことなく、プライベートコーチング、無言の監督、あるいは傍聴のみの受動的な参加といったユースケースに合わせて、やり取りのスタイルを調整することができます。

特定のロールが明示的に割り当てられない場合、すべての参加者が平等に扱われ、DEFAULTロールが割り当てられます。

ロールの割り当て

ロールは、次の方法で割り当てることができます：

1. 新規または既存のコールをカンファレンスに追加する。
2. アクティブなカンファレンス内の参加者のコールレッグを更新する。

ロールを割り当てると、カンファレンスセッション内の参加者の動作と権限をより詳細に制御できます。

使用可能なロールとそれに関連する権限については、次の表をご参照ください：

ロールの移行

カンファレンス参加者のロールは、 コールを更新 (opens in a new tab)する際に変更できます。

ロールの変更は、次の2つの異なるイベントに反映されます：

1. PARTICIPANT_ROLE_CHANGED
2. PARTICIPANT_ROLE_CHANGE_FAILED

カンファレンス履歴を取得する (opens in a new tab)と、各セッションには、特定の参加者が1つのロールでカンファレンスに費やした時間が反映されます。参加者がロールを変更すると、ロールの移行が発生したカンファレンスから実際に退出しなかった場合であっても、ログには、1つのロールでセッションが終了し、同じcallIdの下でセッションを別のロールで開始したことが示されます。

Text-to-Speech

お使いのアプリケーションは、sayメソッドを使って、そのアプリケーションが管理するあらゆるコールでText-to-Speech (TTS) アクションを実行できます。NTT CPaaSは、100以上の言語とアクセントに対応しています。

sayリクエストのペイロードを定義する時は、こちらのテキスト読み上げ表 をご参照ください。その際、この表に出てくる以下の用語にご注意ください：

• Language-code (言語コード) は、選択した言語を2文字で表す略語です。
• VoiceGender (音声の性別)は、MALE (男性) または FEMALE (女性) です。
• VoiceName (音声名) は、音声の名前です。

 
    {
      "text": "text that should be spoken",
      "language": "en",
      "speechRate": 1.0,
      "loopCount": 1,
      "preferences" : {
        "voiceGender": "FEMALE",
        "voiceName": "Joanna"
      },
      "stopOn": {
        "type": "DTMF",
        "terminator": "#"
      }
    }
 

NTT CPaaSプラットフォームは、次の状態が発生した時に、アプリケーションのイベントウェブフックに SAY_FINISHED イベントを送信します：

• テキスト全体が選択した音声に変換され、コールで再生された時、または
• sayメソッドのペイロードに stopOn 節が含まれていて、音声合成の再生中にエンドユーザーが電話機のキー(DTMF)を押した時。この場合、SAY_FINISHED イベントにはペイロードにDTMF入力が含まれます。

sayメソッドでDTMFをキャプチャーする際、キャプチャーするのは1つのDTMF入力のみに制限されますので、ご注意ください。ターミネーターが「any」に設定されている場合、エンドユーザーが電話機で押すDTMFは、SAY_FINISHED イベントに表示されます。ターミネーターが # に設定されていて、エンドユーザーが電話機で 1# を押すと、SAY_FINISHED イベントには # のみが表示されます。

お使いのアプリケーションでより長いDTMF入力をキャプチャーする必要がある場合は、captureDTMFメソッドを使用します。

Speech-to-text

コールAPIプラットフォームでSpeech-to-text (音声テキスト変換) 機能を使用する場合、次に示す2つの使い方があります：

• Capture speech (音声のキャプチャー)： 音声ベースのIVRやチャットボットを構築する場合など、短時間のやり取りを行う時に向いています。
• Transcription (文字起こし)： 長時間のやり取り、または多くの場合、正常に完結したコールの文字起こしを行う時に使います。

キャプチャーと文字起こしのどちらを選択しても、実行できるのは1つのコールレッグのみに限られます。複数のコールレッグを含むカンファレンス、コールまたはダイアログの文字起こしをする場合は、このカンファレンスまたはダイアログに参加している各コールレッグで文字起こしを個別に開始する必要があります。

音声キャプチャー と 音声文字起こし アクションは、次の定義に対応しています：

• 使用する言語。
• 一般的でない単語や特定のスペルの音声認識を強化するカスタム辞書。
• 句読点、適切な大文字と小文字の区別、数値の正規化、流暢性が低い箇所のフィルタリングなど、詳細な書式設定オプションが利用可能です。

音声のキャプチャー

コールレッグで実行する音声キャプチャーアクションは通常、話し言葉をリアルタイムでテキストに変換し、IVR や音声ボットのシナリオでのユーザーインタラクションなど、数秒の長さの短いやり取りを対象としています。どの言語で言葉を発するかを常に指定する必要があります。現在サポートされているすべての言語については、音声認識言語 をご参照ください。

timeoutとmaxSilenceパラメーターの組み合わせにより、音声キャプチャーアクションがユーザー入力をキャプチャーするまで待機する時間と、やり取りを終了する必要があると見なす無音の合計量 (秒単位) を指定することができます。

リクエストで keyPhrases を指定すると、システムは指定されたキーフレーズのトランスクリプトを検索します。terminateOnKeyPhrase パラメーターを使用して、2つの異なる動作を実装できます：

• true に設定 (デフォルト値)：音声キャプチャーアクションは、キーフレーズを検出すると停止します。

例： キーフレーズが「明日」で、エンドユーザーが「明日電車で来ます」と言った場合、音声キャプチャーアクションは「明日」という単語が検出されると停止し、一致したキーフレーズとして「明日」を報告します。

• Set to false (false に設定)： 音声操作は、タイムアウトまたは maxSilence に達するまで続行されます。トランスクリプトの全文を報告し、最初に識別されたキーフレーズが強調表示されます。

例： キーフレーズが「明日」、「電車」で、エンドユーザーが「明日電車で来ます」と言った場合、トランスクリプトの全文は「明日電車で来ます」となり、識別されたキーフレーズは「明日」と報告されます。

音声キャプチャーの結果は、SPEECH_CAPTUREDイベントで報告されます。報告される結果としては、次のようなものが含まれます：

• キャプチャーされた音声の全文。
• 音声キャプチャー中に一致したキーフレーズ (そのキーフレーズが定義されている場合)。
• 音声キャプチャーが終了した理由 (タイムアウトの期限切れ、maxSilence に達した、キーフレーズが見つかった、またはコールの終了)。

音声の文字起こし

コールの文字起こしには、コール時間自体 (つまり、コールの終了時またはコールがカンファレンスに移行した時) を除いて、時間的な制限はありません。文字起こしは、APIメソッドを通じて開始や停止されます。アプリケーションには、イベントタイプ TRANSCRIPTION を含むサブスクリプションが必要ですので、ご注意ください。

コールの文字起こしを開始する際、 文字起こし後のトランスクリプトとして、INTERIM(暫定版)とCOMPLETE(完全版)を両方とも受信するか、COMPLETE(完全版)のみを受信するかを選択できます。

オーディオファイルの再生

アプリケーションは、個々のコールまたはカンファレンス中の任意の時点でオーディオファイルを再生できます。カンファレンス中にファイルが再生されると、すべての参加者にそのファイルの内容が音声として流れます。

オーディオファイルは、再生時にURLから取得することができますし、最初にNTT CPaaSサーバーにアップロードしておくことも可能です。NTT CPaaSサーバーからオーディオファイルを再生するには、まず POST /calls/1/file/upload メソッドを使って、そのファイル (.wav または .mp3) をアップロードする必要があります。upload アクションは、play アクションで指定する必要がある fileId を返します。

URLからオーディオファイルを再生する場合、NTT CPaaSサーバーからファイルをダウンロードするのに時間がかかるため、そのファイルの最初の再生が若干遅れて開始される場合がありますので、ご注意ください。その後の再生では、ファイルがすでにキャッシュされているため、この遅延は発生しません。

コールとカンファレンスの両方でファイルを再生するために loopCount (ファイルの再生回数) を定義できますが、コールでファイルを再生すると、次のような追加の制御機能が提供されます：

• Timeout (タイムアウト)： ファイルを再生する時間 (ミリ秒単位) のことで、定義されていない場合、ファイルは最後まで再生されます。
• Offset (オフセット)： ファイルを再生する開始点 (ミリ秒単位) のことで、定義されていない場合、ファイルは最初から再生されます。

timeout とoffset はどちらも、オーディオファイルを初めて再生する時に適用されます。1より大きい loopCountを指定している間に、この2つのパラメーターに任意の値を指定すると、ファイルの後続のループでは、そのファイルが初めから最後まで再生されます。

PLAY_FINISHED イベントは、次の状態が発生する時に毎回生成されます：

• オーディオファイルの再生が完全に終了した時(loopCount、offsetおよびtimeoutエフェクトを含む)。
• アプリケーションがオーディオファイルの再生の停止を明示的にリクエストした時。

個々のコールにおけるオーディオファイルの再生は、POST /calls/1/call/:id/playAPIcallでオプションのstopOnパラメーターを設定した時点からいつでもエンドユーザーが任意のDTMFキーを押すと中断できます。

この場合、PLAY_FINISHED イベントには、その property 属性に、ファイルが完全に再生されなかったことを示す表示 (playedCompletely:false) とエンドユーザーが送信したDTMF (capturedDtmf:1) が含まれます。

playメソッドでのDTMFのキャプチャーは、1つのDTMF入力のみに制限されますので、ご注意ください。ターミネーターが「any」に設定されている場合、エンドユーザーが電話機で押すDTMFは、SAY_FINISHED イベントに表示されます。

ターミネーターが # に設定されていて、エンドユーザーが電話機の1# ボタンを押すと、SAY_FINISHED イベントには # のみが表示されます。アプリケーションでより長いDTMF入力をキャプチャーする必要がある場合は、captureDTMFメソッドを使用します。

 
    {"conferenceId": null,"callId": "945261b4-0bae-4ff3-9b1d-10485d2dbee8","timestamp": "2022-04-15T15:34:23.884Z","applicationId": "62273b76cc295c00d67f99c3","properties": {	"duration": 14336,	"playedCompletely": false,	"capturedDtmf": "12#"},"type": "PLAY_FINISHED"
    }
 

コールがカンファレンスに移行すると、音声ファイルの再生が停止します。

DTMFのキャプチャーと送信

DTMF (Dual-Tone Multi-Frequency) を介してユーザーまたはリモートシステムとやり取りするには、関連するcapture (opens in a new tab) と send (opens in a new tab)メソッドを使用します。

ユーザーからDTMF入力を収集する方法は複数あります：

1. 一つは、Text-to-Speechファイルまたはオーディオファイルの再生中に収集する方法です。Text-to-Speech を使うか、オーディオファイル を再生するかについては、stopOnパラメーターの使用法について記述している上記のセクションをご参照ください。この方法を採用する場合、収集可能なDTMFの最大長は1桁です。このシナリオでは、収集されたDTMFは、対応する PLAY_FINISHED またはSAY_FINISHED イベントで返されます。
2. もう一つは、capture DTMF (opens in a new tab) メソッドを使って収集する方法です。この場合、任意のサイズの DMTF入力を収集し、必要に応じて終端文字を定義できます。maxLengthパラメーターのみを定義した場合、プラットフォームは、ユーザーがそのサイズ内の入力をするか、タイムアウトに達するまで待機します。terminatorパラメーターを設定すると、その終端文字がエンドユーザーによって入力された場合、定義されたmaxLengthより短いユーザー入力が返されることがあります。 このシナリオでは、収集されたDTMF入力が DTMF_COLLECTED イベントに返されます。
3. 未承諾： 保留中の capture DTMF (opens in a new tab)もstopOnが定義された進行中のSayまたはPlayアクションもない状態でエンドユーザーがDTMF入力を行っている場合、このシナリオでは、プラットフォームは、ユーザーが送信した個々のDTMFごとにDTMF_COLLECTED イベントを送信します。

エンドユーザーは、0-9の数字および／またはw、Wの文字のみを含むDTMF入力を送信できます。

自動機械検出

PHONEの呼び出し先への新しいアウトバウンドコールを作成し、machineDetectionオプションを有効にして、自動機械検出 (AMD) を実行するようにアプリケーションのリクエストを設定します。

コールでAMDを実行するには、次の2つの任意のパラメーターを構成できます：

1. Detection time (検出時間)：AMDは通常、人間が応答したか機械が応答したかを判断するために 3.74 秒の音声を必要とします。*Detection time (検出時間)*パラメーターを使用すると、分析時間を調整できます。例えば：
   • 検出時間を短くすると (最短1秒)、ボイスメールのピックアップをすばやく識別できます。
   • 検出時間を長くすると(最長5秒)、人間か機械かとの識別精度が向上します。
2. Message detection timeout (メッセージ検出タイムアウト)： このパラメーターは、留守番電話が検出された時にメッセージのアナウンスの終わりを検出するための最大時間を示します。これを0に設定すると、システムはメッセージ終了の検出を実行しません。

AMDの分析結果はMACHINE_DETECTION_FINISHEDイベントに表示されます。このイベントには、検出結果を表示する 2つのオプションが含まれています：

1. detectionResult: この値は常にMACHINEまたはHUMANを報告します。
2. confidenceRating: これは各検出クラスの信頼度レベルを含む JSON オブジェクトです。AMDモデルは、HUMAN、MACHINE、MUSIC、RINGING、NOISE、SILENCEおよびOTHERのクラスを分析します。各クラスには、0.0 から 1.0までの独立した信頼度評価が割り当てられています。すべての信頼度の値の合計は、必ずしも1.0とは限りません。

人間と機械のどちらがコールに応答したかを AMDに通知させるだけの場合は detectionResult フィールドを使用し、検出されたすべてのクラスの個々の信頼度スコアに基づいて独自の推定を行う場合は confidenceRating オブジェクトを使用してください。

AMDリクエストでメッセージ検出タイムアウトを有効にすると、追加のイベントをトリガーできます：

• MACHINE_MESSAGE_DETECTION_FINISHED
• MACHINE_MESSAGE_DETECTION_FAILED (失敗した場合)。

音声メッセージや Click-to-Call などの他の音声API とは異なり、NTT CPaaSプラットフォームは、機械がコールに応答したことを検出しても特定のアクションを実行しません。MACHINE_DETECTION_FINISHEDイベントやMACHINE_MESSAGE_DETECTION_FINISHEDイベントを受け取った後、アプリケーションがそのコールをそれからどのように扱うかを判断できるようにしておく必要があります。

レコーディング

レコーディングは、コール、カンファレンスおよびダイアログで使用でき、これらは相互排他的です。

コールのレコーディング

コールをレコーディングできるのは：

• 新しいコールが作成された時。コール作成APIメソッドで任意に設定できるレコーディングオプションを設定します。
• コールに応答した時。コール応答APIメソッドで任意に設定できるレコーディングオプションを設定します。
• 通話中のいずれかの時点。コールレコーディングAPIを使用します。

コールのレコーディングは、次のいずれかの方法で終了します：

1. コールが終了した時
2. コールがカンファレンスに加わった時
3. レコーディング停止APIメソッドを使用する場合は、レコーディング開始後のいずれかの時点

カンファレンスやダイアログのレコーディング

カンファレンスとダイアログは、次のいずれかの手順でレコーディングできます。

• 新しいカンファレンスまたはダイアログが作成された時にレコーディング (オーディオまたはオーディオとビデオの両方) をアクティブにする
• レコーディングを明示的に開始するには、カンファレンスレコーディング開始API (opens in a new tab) または ダイアログレコーディング開始APIメソッド (opens in a new tab) を使用します。

新しいレコーディングを開始する時に、オーディオのみを録音するか、オーディオとビデオの両方を録音・録画するかを選択するだけでなく、すべての参加者のレコーディングをまとめる必要があるかどうかも選択できます。

• 結合を選択すると、全参加者が1つのオーディオファイルまたはビデオ ファイルにマージされます。
• 結合を選択しない場合、全参加者はそれぞれ独自のオーディオまたはビデオファイルに分けられます。

レコーディングが終了するのは：

• カンファレンスまたはダイアログが終了(ハングアップ)した時。
• カンファレンスまたはダイアログにレコーディング停止APIメソッドが使われた時。

オンデマンドのレコーディング結合

レコーディングをまとめることを明示的に要望せずにカンファレンスまたはダイアログを録音する場合 (つまり、すべての参加者のトラックが1つのファイルのみにまとめて録音する場合)、レコーディングによって複数のオーディオファイルまたはビデオファイル (カンファレンスまたはダイアログがアクティブな時に Start/Stop レコーディングアクションごとに参加者各自に1ファイル)が作成されます。

これらの個々のメディアファイルは、NTT CPaaSのストレージから入手可能な限り、レコーディング後いつでも ダイアログ (opens in a new tab) または カンファレンス (opens in a new tab) のレコーディングに結合できます。NTT CPaaS は、個々のファイルがSFTP サーバーに転送されると、それらのファイルを結合することはできません。

オンデマンド結合をリクエストする場合、元の個々のメディアファイルの削除または保存をリクエストできます。

マルチチャネルレコーディング

ダイアログまたはカンファレンスのオンデマンド結合をリクエストする際、結合されたメディアファイルをマルチチャネルにするようにリクエストできます。その場合、ダイアログまたはカンファレンスの各参加者は個別のオーディオチャネルに分離されます。

マルチチャンネルメディアファイルを持つことは、次のような場合に役立ちます：

• 例えば、各参加者が何を述べたかについて、明確かつ疑いの余地のない証拠を提示することが求められる、法的およびコンプライアンス上の状況が生じた時。
• 文字起こしと分析：一部の文字起こしツールは、適切な話者識別に対応しておらず、各話者の音声を別々のチャネルに分離する必要があります。
• マルチチャネルレコーディングは、オンデマンド結合でのみ利用できます。

レコーディング結果の表示とダウンロード

APIを介して特定のオーディオまたはビデオファイルを検索してダウンロードするには：

1. いずれかの GET 記録メソッドを使用して fileId を取得します (つまり、コール、カンファレンス、またはダイアログを基準に)。callId、conferenceId、dialogId で録音を検索したり、すべてのコール、カンファレンス、ダイアログの既知の録音をすべて取得したりできます。
2. ファイルのバイトストリーム表現をダウンロードするには、GET /calls/1/recording/file/：file-id メソッドを使います。オーディオファイルは常に .wav 形式で、ビデオファイルは常に .mp4 形式でそれぞれレンダリングされます。

NTT CPaaS のWebインターフェイスからレコーディング結果を検索してダウンロードするには：

1. Voiceチャネルアプリケーションのレコーディングタブ (opens in a new tab)に移動します。
2. Calls (コール)、Conferences (カンファレンス) または Dialogs (ダイアログ) を選択して、レコーディング結果の一覧を表示します。
3. 特定のレコーディングエントリーを展開すると、結合済みか非結合かに関係なく、関連ファイルのリストが表示されます。クラウドストレージに保存されているファイルは、関連するメタデータjsonファイルと同様にダウンロードできます。

レコーディング結果のカスタムメタデータの設定

コール、カンファレンスまたはダイアログのレコーディングを開始する際、ユースケースに基づいて、そのレコーディングに関連するコンテキストデータを保存するのに役立つキーと値のペアを定義できるカスタムデータjsonオブジェクトを設定するオプション機能を使用することができます。レコーディングは、コール、カンファレンスまたはダイアログが存在している間、何回でも開始したり停止したりできます。また、各レコーディングアクションには独自のカスタムメタデータが定義されており、このカスタムデータは、レコーディング結果を取得する時にファイルレベルで反映されます。このカスタムデータは、コール、カンファレンスまたはダイアログのレコーディング結果の一覧を取得する時のクエリ要素として使用することはできません。

レコーディングファイル名の命名規則

レコーディングしたコール、カンファレンスまたはダイアログのファイル名は、結合されているか否かに関わらず、常に fileId.extです。拡張子のextは、レコーディングがオーディオのみの録音データか、ビデオのみの録画データかによって、wavまたはmp4に変わります。

SFTP経由のレコーディング結果の転送

レコーディングをSFTP経由でサーバーにプッシュする場合は、 (opens in a new tab)NTT CPaaS UIから (opens in a new tab)SFTP構成を定義します。SFTPサーバーに正常に転送されたファイルはNTT CPaaSストレージから削除されますが、すべてのコールAPIレコーディングのリストを取得する時に参照されたままになります。

デフォルトでは、 fileId.zipがSFTPサーバーにプッシュされるコールAPIレコーディングの命名規則として適用されています。zipファイルには、メディアファイル (wavまたはmp4) とそれに対応する jsonファイルの両方が入っており、そのレコーディングに関連するメタデータもその中に含まれています。zipアーカイブ内のファイルには、 fileIdというファイル名が付けられています。

コールAPIレコーディングメソッドを使用する際、関連するレコーディング開始メソッドでオプションのfilePreFixパラメーターを指定すると、その結果、サーバーにプッシュされる zipファイルの名前に影響が出る可能性があります。但し、SFTPを使用しない場合は、このパラメーターを指定しても何ら影響を受けることはありません。アクティブなSFTP設定があり、filePrefixを "myCustomName" に設定する場合、zipファイル名は常に myCustomName.zipになります。この機能を使用する際は、サーバーにプッシュした際にZIPアーカイブが上書きされないよう、必ず一意のプレフィックスを使用するようにしてください。

WebSocketストリーミング

WebSocketオーディオストリーミングは、WebSocketプロトコルを使用して、インターネット経由でリアルタイムのオーディオデータを送信します。クライアントとサーバーの間に永続的な双方向接続を確立し、ライブボイスチャット、自動音声応答システム、リアルタイムオーディオモニタリングなどのアプリケーションとの継続的なオーディオ交換を可能にします。この接続と効率的なデータ転送により、従来の方法と比較してレイテンシーが短縮され、パフォーマンスが向上します。

サポートされているWebSocketストリーミングオプション

NTT CPaaSのコールAPIは、WebSocketストリーミングによる外部メディア処理サービスとの統合をサポートしています。ユースケースに応じて、2つの異なるオプションを提供します：

1. ストリーミングメディアアクション

• 特定のコールレッグで開始および停止します。
• そのコールレッグから外部サービスにオーディオストリームを複製し、メディア置換を実行するオプションを提供します。
• メディア置換がアクティブな場合、そのコールレッグの元の音声は外部サービスからの音声に置き換えられるため、カンファレンスまたはダイアログの他の参加者には、元のストリームではなく、置き換えられた音声が聞こえます。
• 一般的なユースケース：
  • 指定されたコールレッグの音声を外部の音声文字起こしまたは感情分析サービスにストリーミングする。
  • 外部AIサービスを使用して、指定されたコールレッグの音声を変更し、置き換える。例： 不適切な言葉のフィルタリングや音声補正。

2. WebSocketエンドポイント

• 外部メディア処理サービスをカンファレンスまたはダイアログの個別の参加者として追加します。
• ミュートされていないすべての参加者から音声を受信します。
• 外部サービスによって生成された音声は、そのカンファレンスまたはダイアログのすべての参加者に聞こえます。
• 一般的なユースケース：
  • 会話型AIサービス (ボイスボット) をカンファレンスやダイアログに統合
  • すべての参加者の音声を、話者のダイアライゼーションをサポートする外部の文字起こしサービスにストリーミングします。
  • すべての参加者の音声を外部録音サービスにストリーミングします。
  • すべての参加者の音声を外部ブロードキャストサービスにストリーミングします。

これらの統合方法を使用して、リアルタイムオーディオ処理やその他の高度なメディア機能をNTT CPaaSのコールアプリケーションに組み込むことができます。

ストリーミングメディアアクション

コールAPIを使用すると、WebSocketを使用して、アプリケーションから任意のホストにアウトバウンドコールメディアをストリーミングできます。現在、オーディオストリーミングのみがサポートされています。

オーディオストリーミングは、コールレッグごとに構成されます。ストリームを開始する前に、少なくとも1つの新しいメディアストリーム構成を作成する必要があります。次に、コール内で構成IDを使用して、ストリーミングメディアを開始／停止します。メディアは、一連の生のバイトとしてストリーミングされます。

メディア置換無しのストリーミング

ここでは、メディア置換無しのストリーミングがどのように見えるかについて説明します。2人の参加者がカンファレンスブリッジを介して互いに話している時に、参加者 A のオーディオは外部の文字起こしサービスにルーティングされ、参加者 B には 参加者 A がそのまま聞こえる必要があるとします。メディア置換無しのストリーミングでは、発信メディアが別のリスナーにストリーミング (フォーク) されます。

メディア置換によるストリーミング

次に、上記と同じ例を使って、外部ホストがオーディオフィルタリング (ボイスチェンジャー、プロファニティフィルターなど) といったサービスを提供するロールを担う場合について説明します。この場合、この場合、加工された音声がカンファレンスに配信され、これがカンファレンスの全参加者に聞こえる音声となります。

メディアストリーミング構成の作成

まず、メディアストリーム構成オブジェクトを作成します。このオブジェクト内で、WebSocketホストのURLと、アクセスに必要な認証情報（ある場合）を指定する必要があります：

 
    REQUEST
    {
     "type": "MEDIA_STREAMING",
     "name": "emea-ws-stream",
     "url": "wss://example-host.com:3002",
     "securityConfig": {
       "type": "BASIC",
       "username": "example-username",
       "password": "example-password"
  }
}
 
    RESPONSE
    {
      "id": "63493678a2863268520c0038",
      "type": "MEDIA_STREAMING",
      "name": "emea-ws-stream",
      "url": "wss://example-host.com:3002"
}
 

wsと wssの両方がサポートされています。応答には、新しく作成された MediaStreamConfigオブジェクトのIDが含まれます。

通話中にメディアのストリーミングを開始するには、start-media-streamリクエストを作成します。リクエスト内で、以前に作成した構成のIDを指定し、ホストがメディアを置き換えるかどうかを指定します。

 
    {
    "mediaStream": {
        "audioProperties": {
            "mediaStreamConfigId": "63493678a2863268520c0038",
            "replaceMedia": true
        }
    }
}
 

すべてが正常に完了した場合、ホストが最初に受け取るメッセージは次のようになります：

 
    {
    "callId":   "callIdPlaceHolder",
    "sampleRate":   48000,
    "packetizationTime":    20,
    "customData":   {
        "message":  "customDataPlaceHolder"
    }
}
 

このメッセージには、次のフィールドが含まれています：

• callId - メッセージに対応する callIdです。ホストが複数のコールを処理する可能性がある場合に便利です。
• sampleRate - ストリーミングされるオーディオのサンプリングレートです。単位はキロヘルツ(kHz)で、デフォルトは48kHzです。
• packetizationTime - 2つの連続するパッケージがホストに送信される間の経過時間です。単位はミリ秒 (ms) で、デフォルトは20msです。
• customData - 開発中 (完全にはサポートされていません)

インバウンドオーディオストリームの解析

接続を確立して最初のメッセージを送信した後、NTT CPaaSプラットフォームはホストにオーディオパケットを送信し続けます。パケットは packetizationTime (このフィールドに入力した秒数の値) ごとに送信されます。パケットには純粋なオーディオのみが含まれます。 48kHzでサンプリングされたオーディオの場合、20msのオーディオには次のものが含まれます：

• number_of_samples = 48kHz x 20ms = 960サンプル

オーディオは生データでストリーミングされ、各オーディオサンプルは16ビットの符号付き整数としてエンコードされ、2バイト値として表わされます。従って、どのインバウンドメッセージも、1920バイト (960 x 2) が含まれているのが理想的です。但し、ネットワーク上の問題が発生した場合、メッセージ内で複数のパケットが送信されることがあります。これらのパケットは、必ず1920バイトの倍数 (3840、5760、7680など) になります。

メディア置換

メディアストリームリクエストがメディアを置き換えるように設定されている場合、NTT CPaaSプラットフォームでは1920バイトのパケットが送り返されることを想定しています。ネットワークエラーが発生し、複数のパケットが1つのクラスタとして送信された場合でも、ホストは常に1920バイトのパケットを送り返す必要がありますので、ご注意ください。これらのパケットはコールに挿入され、他の参加者に配信されます。従って、メディア置換がアクティブな場合、メディアの1つのストリームを送り返すだけで、NTT CPaaSプラットフォームはそれをコールに加わっている他の参加者に配信します。

メディア置換が設定されていない場合、NTT CPaaSプラットフォームはホストからのインバウンドメッセージを無視します。

WebSocketエンドポイント

WEBSOCKETエンドポイントを使用して、WebSocket経由で外部メディアサービスへのアウトバウンドコールレッグを作成できます。コールレッグとして、次のものに結合できます：

• 複数の参加者が参加するカンファレンス。
• 参加者が 1 人のダイアログ。

これは、参加者のそれぞれのエンドポイントタイプ (PHONE、SIP、WEBRTC、VIBER、WHATSAPP) に関係なく可能です。

WebSocketストリーミング構成の作成

WebSocketストリーミングを有効にするには、 WebSocketストリーミング構成オブジェクト (opens in a new tab)を作成する必要があります。このオブジェクト内で、WebSocketホストのURLを指定し、構成タイプをWEBSOCKET_ENDPOINTに設定します。

 
REQUEST
{
  "type": "WEBSOCKET_ENDPOINT",
  "name": "ai-assistant-us-west",
  "url": "wss://example-host.com:3001",
  "sampleRate": "8000"
}
 
RESPONSE
{
    "id": "63493678a2863268520c0038",
    "type": "WEBSOCKET_ENDPOINT",
    "name": "ai-assistant-us-west",
    "url": "wss://example-host.com:3001"
}
 

WebSocketエンドポイントで認証が必要な場合は、現在 customData キーと値のペアを使用してこれをサポートしていることにご注意ください。WebSocketエンドポイントは、customData を含む websocket:connected イベントを送信できるように、接続を許可する必要があります。

WebSocketエンドポイントの接続

WEBSOCKETコールレッグは、 コールの作成 (opens in a new tab)、 新しいコールとの接続 (opens in a new tab)、 新しいコールの追加 (opens in a new tab)、 ダイアログの作成 (opens in a new tab)などのメソッドで開始できます。WEBSOCKET のアウトバウンドコール作成する場合は、WebSocket構成IDを指定します。

WEBSOCKETのコールレッグを作成すると、customDataで定義されたキーと値のペアがwebsocket:connectedイベントの一部としてWebSocketサーバーに送信されます。customData の最大長は512バイトです。

WebSocketメッセージ

WebSocketメッセージは、SIPシグナリングやRTPパケットと機能的に同等であり、シグナリングを処理するテキストメッセージと、メディアデータを伝送するバイナリメッセージがあります。

確立されたWebSocket接続で送信される最初のメッセージはテキストベースで、JSONペイロードが含まれています：

 
{
    "event": "websocket:connected",
    "content-type": "audio/l16;rate=16000",
    "key1": "value1",
    "key2": "value2"
}
 

最初のテキストメッセージの後、後続のメッセージはテキスト(DTMFディジット)またはバイナリにすることができます。

WebSocketインターフェイスで現在サポートされているオーディオコーデックは、リニアPCM16 ビットで、サンプルレートは8kHz、16kHz、24kHzまたは32kHz、フレームサイズは 20msです。

WebSocketに接続されているコールのいずれかの当事者がDTMFトーンを送信すると、WebSocketでイベントがトリガーされます。このイベントは、JSON ペイロードを含むテキストメッセージであり、オーディオフレーム間でインターリーブされ、次の形式になります：

 
{
    "event": "websocket:dtmf",
    "digit": "3",
    "duration": 250
}
 

WebSocketへのオーディオの書き込み

オーディオをコールに送り直すには、WebSocket経由でバイナリメッセージを送信します。オーディオ形式は、前のセクションで説明した仕様と一致する必要があります。各メッセージは、サンプルレートに応じて正確に 320、640、960または 1280バイト である必要があり、オーディオの20msのセグメントを表す必要があります。

メッセージは、再生前にバッファに保存されるため、リアルタイム再生を超える速度で送信できます。これにより、メッセージサイズの要件(320、640、960または1280バイト)を遵守していれば、1回の操作でオーディオファイル全体を転送できます。但し、NTT CPaaSのバッファ容量は 1024メッセージに制限されており、これは約20秒のオーディオに相当します。ファイルがこの長さを超える場合は、データの損失を防ぐために、各メッセージの間に約18から 19msのディレイを設けるようにしてください。

一括コール

一括APIメソッドを使用すると、1つのリクエストで複数のコールを作成し、スケジュール設定された一括コールを管理できます。一括メソッドで生成されたコールは、単一のコールと同じオプションをサポートします。一括コールは、PHONEの呼び出し先に対してのみ作成できます。

一括コールは、次のような追加パラメーターに対応しています：

• スケジューリング： コールの生成を開始するタイミング、ならびにこれらのコールの発信時間枠を設定します。
• 有効期間：NTT CPaaSプラットフォームがこれらのコールの生成をどのくらいの期間試みるべきかを設定します。このパラメーターは、呼び出し時間枠を定義する時に使用します。
• コール頻度： 指定した時間単位に開始するコールの本数 (1 分あたり15本、1 時間あたり60本など) を設定します。

複数の一括コールをバンドルし、それぞれが独自のスケジュールと有効期間を持つ複数の呼び出し先をターゲットにすることができます。

一括コールを一時停止、再開、キャンセルまたは再スケジュールすることができます。一括コールに加えられる新しいコールごとに、個別に作成されたコールと同じイベント状態の更新ストリーム (call_started、call_pre_established、call_ringingなど) が生成されますので、アプリケーションは個々のコールの処理方法を完全に可視化して制御することができます。

例えば、リトライポリシーが5回の一括コールを作成したいとします。リトライごとに、アプリケーションは従来のCALL_* イベントを受け取ります。アプリケーションをBULK_STATUS_EVENT イベントにサブスクライブすると、アプリケーションは特定の一括の呼び出し先に対して実行された最後のリトライを認識できます。このイベントは、一括リクエストのコール (呼び出し先) 部分ごとに生成され、その特定の呼び出し先へのコールの配信の成功を報告するか、コールの失敗を報告します。

呼び出し先への接続が成功した場合、コールが完了した後でのみ BULK_STATUS_EVENT が送信されます。

コールにWebRTCを使用

NTT CPaaS WebRTC SDKは、コールAPIと組み合わせずに単独で使用することもできますが、WebRTCとコールAPIを組み合わせると、次の利点があります：

• バックエンドアプリケーションからのwebRTCコールを包括的かつきめ細かく制御できます。
• webRTCコールは簡単にカンファレンスに参加したり、退出したりできます。
• webRTCコールを、サポートされている他のエンドポイント (電話、SIP) と同じカンファレンスに含めることができます。
• バックエンドアプリケーションにインバウンドwebRTCコールのルーティングロジックを実装できます。
• webRTCコールでは、Text-to-Speechの再生、DTMFの収集と送信、オーディオファイルの再生が可能です。

コールにWebRTCを使用するには、次のことを行う必要があります：

• webRTCのはじめに セクションの手順に従って、webRTCアプリケーションを宣言する。
• NTT CPaaS webRTC SDK (opens in a new tab) をウェブまたはモバイル (Android/iOS) のアプリケーションに統合する。
• webRTCのSDK Wiki(Javascript SDK (opens in a new tab)、Android SDK (opens in a new tab)、iOS SDK (opens in a new tab) に記載されているように、コールAPIプラットフォームに関連する特定のガイドラインに従ってください。

コールAPIとCPaaSX

コールAPIプラットフォームはNTT CPaaS CPaaSXをサポートしています。特に、コールAPIを使用すると、以下のCPaaSX機能を利用できます：

• サブスクリプション
• アプリケーション
• エンティティ

イベントサブスクリプションの使用は必須ですが、コールAPIを使用する場合、アプリケーションとエンティティの使用は任意です。

アウトバウンドコールのApplicationIdとEntityId

アウトバウンドコールでCPaaSXのapplicationIdおよび／またはentityIdを設定するには、以下のメソッドを使用し、 platformオブジェクトにapplicationIdおよび／またはentityIdの値を設定します：

• コールの作成 (opens in a new tab)
• コールの一括作成 (opens in a new tab)

同様に、applicationIdおよび/またはentityIdですでにタグ付けされている 既存のコールを新しいコールでブリッジする場合、親コールのapplicationIdおよび／またはentityIdは、新しいアウトバウンドコールで複製されます。これらの関連メソッドは以下のとおりです：

• 新しいコールへの接続 (opens in a new tab)
• ダイアログの作成 (opens in a new tab)

インバウンドコールのApplicationIdとEntityId

インバウンドコールは番号の音声セットアップで指定されているapplicationIdやentityIdでフラグが立てられます。このセットアップは、(API (opens in a new tab)によって定義されるか、Webインターフェイス上のNumbersアプリケーション内のインバウンド構成を介して定義されます。

コールにおけるCPaaSXアプリケーションとエンティティの定義の結果

CPaaSXのapplicationIdおよび／または entityIdがインバウンドコールやアウトバウンドコールに定義されている場合、これらの applicationIdや entityIdが以下に反映されます：

• そのコールに関連するすべてのコールAPIイベント。
• Webインターフェイスから生成およびダウンロードされた詳細な 音声レポート (opens in a new tab) 。
• コール (opens in a new tab)ß、 カンファレンス (opens in a new tab)および ダイアログ (opens in a new tab) の履歴CDR。
• コール (opens in a new tab)、 カンファレンス (opens in a new tab)、および ダイアログ (opens in a new tab) は CDR を記録します。

さらに、, applicationIdとentityIdは、イベント・サブスクリプションの追加フィルタ基準として使用できます。例えば、以下のように定義します：

• callsConfigurationId "voice-prod-app"
• 2つのapplicationId"app1 "と "app2"

次のようにすることができます：

• 条件として callsConfigurationId "voice-prod-app" のみを持つ1つのイベントサブスクリプション。
• 条件として callsConfigurationId "voice-prod-app" と applicationId "app1" を持つ1つのイベントサブスクリプション。
• 条件として callsConfigurationId "voice-prod-app" と applicationId "app2" を持つ1つのイベントサブスクリプション。

callsConfigurationId "voice-prod-app" に関連するコールに使用されるサブスクリプションは、コールで applicationIdも定義されているかどうか、また定義されている場合はその値によって異なります。

トラブルシューティング

エラーの確認

HTTPエンドポイントは、標準のHTTPステータスコード を返します。

eventUrlウェブフックに送信されるCALL_FINISHED や CALL_FAILED イベントには、イベントのproperties要素内の errorCodeオブジェクトに、ハングアップの原因または失敗の理由が含まれます。

eventUrlウェブフックに送信されるERROR イベントには、イベントの properties 要素内の errorCodeオブジェクトに、失敗した関連アクションに関するエラーの詳細が含まれます。

 
    {"conferenceId": null,"callId": "4828889f-b53e-48ae-821d-e72c9279db97","timestamp": "2022-04-25T14:24:48.366Z","applicationId": "62273b76f7295c00d67f84c3","properties": {	"errorCode": "FILE_CAN_NOT_BE_PLAYED",	"errorDetails": "Playing file failed"},"type": "ERROR"
    }
 

ライブコールとカンファレンスの確認

アクティブな (ライブ) コールの一覧または特定のライブコールに関する情報をAPI経由で照会できます。それぞれ GET /calls/1/calls または GET /calls/1/calls/:id メソッドを使用します。

同様に、APIを介してアクティブな (ライブ) カンファレンスのリストや特定のライブカンファレンスに関する情報を照会できます。GET /calls/1/conferencesまたはGET /calls/1/conferences/:idメソッドを使用します。

履歴ログとレポートの確認

Webインターフェイスから

NTT CPaaSのWebインターフェイスからAnalyze (アナライズ) モジュールを通じてアクセスできる ログ (opens in a new tab)とレポート (opens in a new tab)を確認することで、これまでに生成したコールの履歴リストを取得できます。

APIの使用

APIを介して、過去のコール履歴のリストまたは特定の過去のコールに関する情報を照会できます。GET /calls/1/calls/historyまたはGET /calls/1/calls/:id/historyメソッドをそれぞれ使用します。

データを利用できるローリング期間は2か月間です。クエリパラメーターを使用すると、特定の2つの日付の間に発生したFAILED に等しい状態の過去のすべての INBOUND コールを照会するなど、 GET リクエストのフィルタリングが可能になります。