通話（コール）

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

コールは、着信通話や発信通話を処理するアプリケーションを作成できるようにします。アプリケーションは、音声シナリオ ロジックを実装し、コールAPIを使って、選択した音声チャネル (PSTN、webRTC、SIP) を介して通話や会議時のアクションを制御したり、実行したりします。

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

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

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

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

コンセプト

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

• コール設定
• 番号
• コールAPI
• イベント

コール設定 [#calls-configuration]

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

コール設定の作成 [#creating-a-calls-configuration-concepts]

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

イベント サブスクリプションの関連付け [#event-subscription-association-concepts]

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

• Create a subscription (サブスクリプションの作成)：手順の最初のステップは、少なくとも 1 つのイベントサブスクリプションを作成することです。サブスクリプションの作成や管理は、NTT CPaaSのWebインターフェイス上で、またはAPIを通じて行うことができます。
  1. チャネルの種類を指定する: イベント サブスクリプションを設定するときに、チャネルの種類をVOICE_VIDEOとして指定します。これにより、アプリケーションが処理するイベントの性質が定義されます。
  2. プロファイルの定義: サブスクリプションのプロファイル セクションには、アプリケーションの Webhook の詳細を含める必要があります。これには、Webhook の URL とセキュリティ仕様が含まれ、安全でダイレクトな通信が保証されます。
  3. 目的のイベントを一覧表示する: サブスクリプションの events 配列で、Webhook に送信するすべての Calls API イベントを一覧表示します。これらは、アプリケーションの機能に関連するすべてのイベントを含むコンマ区切りのリストとして指定する必要があります。考えられるすべての呼び出し API イベントの一覧は、 イベント Webhook にあります。
  4. 条件オブジェクトの設定: 最後のステップは、サブスクリプションのcriteriaオブジェクトでcallsConfigurationIdを指定することです。これにより、イベント サブスクリプションが呼び出し構成に直接リンクされ、適切なイベントがアプリケーションにルーティングされます。

同じ callsConfigurationId 条件を使用する複数のサブスクリプションを定義して、イベントの処理方法を整理できます。このアプローチにより、さまざまなイベントタイプを個別のWebhookにルーティングできるため、構造と処理効率が向上します。その場合は、各サブスクリプションにその callsConfigurationId の一意のイベント タイプのセットが含まれていることを確認します。

番号 [#numbers-concepts]

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

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

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

この番号は、アプリケーションに新しい発信通話の発信者 ID として指定できます。この番号はアプリケーションに関連付ける必要はなく、同じ番号を異なるアプリケーションによって生成される発信通話の 発信者 ID として表示させることもできます。

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

NTT CPaaS 音声番号をアプリケーションにリンクさせるるには、FORWARD_TO_SUBSCRIPTIONアクションとcallsConfigurationIdを併用して API を使用する必要があります。

コールAPI [#calls-api-concepts]

アプリケーションが通話や会議内で実行する必要があるアクションは、REST API を介して行われます。APIは、HTTPステータスコードとペイロードで同期的に応答し、要求されたアクションの受信を確認します。

下記に示すいくつかの メソッド が利用できます。

• 通話を作成し、通話の詳細を取得します。
• 会議を作成し、会議の詳細を取得します。
• 通話や会議でアクションを実行します。
• オーディオファイルと録音を管理します。

イベント [#events-concepts]

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

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

コールAPI について

通話、会議、ダイアログ [#calls-conferences-and-dialogs-understanding-calls-api]

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

このドキュメントの残りの部分と API ドキュメントでは、コール レッグはコールと呼ばれます。

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

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

通話は複数の方法で接続(ブリッジ)できます。

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

ダイアログと接続/会議には他にも違いがあります。その主なものは次のとおりです。

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

すべての通話には独自の一意のコール ID があります。すべての会議またはダイアログには、独自の一意の会議ID またはダイアログID があります。これらの識別子は互換性はありません。

これを念頭に置いて、さまざまなユースケースに推奨されるコールブリッジング方法を次に示します。

• 着信コールをアウトバウンド宛先にブリッジする必要があります(「コール転送」):ダイアログが最適です
• 2 つの発信コールをブリッジする必要があります。 ダイアログが最適です
• 2 人以上の参加者を橋渡しする必要がある: 会議または Connect メソッドを使用する
• 「保留中」の状況を実装する必要があります:「保留中」の参加者が
  • 会議から一時的に削除できます。
  • メディアは、保留時間中に参加者のコール レッグで再生されます。
  • 通話が再開されると、参加者のコール レッグは別の参加者との会議に戻されます。
• 「スマートダイヤラー」のユースケースを実装するには、会議または接続メソッドを使用します。
  • エージェントが会議に接続されます。
  • 接続された発信コールは、その会議でエージェントに接続されます。

通話状態 [#call-states-understanding-calls-api]

次のセクションでは、各コール状態の図と詳細情報を提供します。

発信通話の状態 [#outbound-call-states-understanding-calls-api]

次の図は、発信通話の様々な状態と、これらの状態遷移を表すイベントを示しています。

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

発信通話は、常に次のいずれかの最終通話状態になります。

これらの最終通話状態の場合、先行する CALL_FINISHED または CALL_FAILED イベントには、通話がハングアップまたは確立できなかった理由が含まれます。

着信通話の状態 [#inbound-call-states-understanding-calls-api]

次の図は、着信通話の様々な状態と、これらの状態遷移を表すイベントを示しています。

着信通話は、常に次のいずれかの最終通話状態で終了します。

これらの最終通話状態の場合、先行する CALL_FINISHED または CALL_FAILED イベントには、通話がハングアップまたは確立できなかった理由が含まれます。

参加者の状態 [#state-of-participants-understanding-calls-api]

マルチパーティ通話 (1 対 1 または実際の会議) を処理する場合、アプリケーションは複数のイベントをサブスクライブして、参加者の状態を適切に追跡できます。

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

エンドポイント [#endpoints-understanding-calls-api]

通話または会議を作成する時は、接続先のエンドポイントまたはエンドポイントのリストを指定する必要があります。

NTT CPaaS プラットフォームでは、次のタイプのエンドポイントがサポートされています。

1. 電話: PHONE エンドポイントタイプは、常に E.164 形式の 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を設定できます。

通話のフロー [#call-flows-understanding-calls-api]

着信コールフロー [#inbound-call-flow-understanding-calls-api]

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

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

• API経由:
  • NTT CPaaS 番号で、アクション タイプ FORWARD_TO_SUBSCRIPTION を使用して音声設定を作成し、callsConfigurationIdを含めます。
• Webインターフェイス経由:
  • Numbersアプリケーションに移動し、番号を選択します。
  • [Voice] タブを選択します。
  • 転送アクションが サブスクリプションに転送 である受信設定を作成し、callsConfigurationIdを指定します。

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

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

アプリケーションが CALL_FAILED または CALL_FINISHED イベントを受信すると、そのイベントのペイロードを検査して、通話状態と通話の終了または失敗の原因に関する、より詳細な情報を取得します。

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

発信通話のフロー [#outbound-call-flow-understanding-calls-api]

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

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

接続/会議を使った2つの通話の接続 [#connecting-two-calls-with-connectconference-understanding-calls-api]

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

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

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

• 会議室を作成し、CONFERENCE_CREATED イベントで確認します。
• 指定した各通話を参加者として追加し、PARTICIPANT_JOINING イベントと PARTICIPANT_JOINED イベントで確認します。

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

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

ダイアログを使った2つの通話の接続 [#connecting-two-calls-with-dialog-understanding-calls-api]

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

次のシーケンス図のコール フローは、エンド ユーザー A への発信通話を 1 つ作成することで開始するアプリケーションを示しています。ダイアログは、親通話と子通話の概念を処理します。ダイアログ上で 2 つの通話を接続する最も一般的な方法は次のとおりです

• 既存の(確立された)コールを、着信か発信かにかかわらず、親コールにする場合。
• ダイアログ作成要求で接続先を指定するには、これが子呼び出しになります。

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

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

会議のフロー [#conference-flow-understanding-calls-api]

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

会議に参加者を追加する方法は複数あります。

• 既存の(ライブ)通話を会議に移動できます。
• 新しい発信コールを開始し、単一の API メソッドを使用して既存の会議にすぐに移動できます。

次の会議フローでは、既存の通話を会議に追加する際、エンドユーザーAとエンドユーザーB への通話がすでにライブになっていることを前提としています。会議は最初に作成する必要があり、一意の conferenceIdを含む CONFERENCE_CREATED イベントによって確認されます。参加者を呼び込むには、conferenceId およびエンドユーザーA とエンドユーザーB のそれぞれの通話の一意の callId が両方必要です。

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

アプリケーション間の通話の転送 [#transfer-calls-between-applications-understanding-calls-api]

上で説明したように、呼び出しは常にアプリケーションに属するため、呼び出し API プラットフォームは、その呼び出しの状態またはその呼び出しで実行されたアクションに関連するイベントを送信するために必要な Webhook を認識します。呼び出し API を使用すると、アプリケーション転送メソッドを使用して呼び出しのアプリケーション所有権を変更できます。

たとえば、IVR （自動音声応答） シナリオを実装する 1 つのアプリケーションと、自社開発のコール センター プラットフォームを表す別のアプリケーションについて考えてみましょう。IVR （自動音声応答） アプリケーションへの着信コールは IVR アプリケーションが所有しますが、IVR （自動音声応答） シナリオでのエンド ユーザーの選択に従って、そのコールは IVR （自動音声応答） からコール センターに転送する必要があります。このシナリオでは、IVR （自動音声応答） アプリケーションは、コール センター アプリケーションへのそのコールのアプリケーション転送を要求します。

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

会議の役割

会議中に柔軟で安全な通信フローを提供するために、Calls API では、参加者への特定のロールの割り当てがサポートされています。会議の役割は、可視性、発言、リスニングに関する各参加者の能力を決定します。

会議の参加者に特定の役割を割り当てることで、セッション内の他のユーザーの全体的なエクスペリエンスを損なうことなく、プライベート コーチング、サイレント スーパービジョン、受動的な出席などのユース ケースに合わせて対話モデルを調整できます。

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

役割の割り当て

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

1. 新規または既存の通話を会議に追加する。
2. アクティブな会議内の参加者のコールレッグを更新する。

役割を割り当てると、会議セッション内の参加者の動作と権限をより詳細に制御できます。

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

役割の移行

会議参加者の役割は、 update call メソッドを使用して変更できます。

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

1. PARTICIPANT_ROLE_CHANGED
2. PARTICIPANT_ROLE_CHANGE_FAILED

会議履歴を取得すると、各セッションには、1 つの役割で特定の参加者が会議に費やした時間が反映されます。参加者がロールを変更すると、参加者がこの移行中に実際に会議から退出しない場合でも、ログには、セッションが 1 つのロールで終了し、別のロールで同じcallIdに対して開始されたことが示されます。

テキスト読み上げ [#text-to-speech-understanding-calls-api]

アプリケーションでは、say メソッドを使って、そのアプリケーションによって管理される任意のコールでText-to-Speech (TTS) アクションを実行できます。

say リクエストペイロードを定義するときは、この text-to-speech table を参照してください。

• 言語コードは、選択した言語の 2 文字の略語です。
• VoiceGender は MALE または FEMALE です。
• VoiceName は音声の名前です。

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-understanding-calls-api]

音声テキスト変換テクノロジーをコールAPI プラットフォームで使用する場合、次に示す2つのアプローチのいずれかを通じて使用できます。

• 音声のキャプチャ: 音声ベースのIVR （自動音声応答）やチャットボットを構築する場合など、短時間の対話を対象としています。
• 文字起こし: 長時間の対話、または通常は完全な通話の文字起こしを目的としています。

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

音声キャプチャ と 音声文字起こし アクションでは、次の定義がサポートされています。

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

音声キャプチャ [#speech-capture-understanding-calls-api]

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

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

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

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

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

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

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

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

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

音声の文字起こし [#speech-transcription-understanding-calls-api]

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

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

オーディオファイルの再生 [#playaudio-files-understanding-calls-api]

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

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

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

通話と会議の両方でファイルを再生するために loopCount (ファイルの再生回数) を定義できますが、通話でファイルを再生すると、次のような追加の制御機能が提供されます。

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

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

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

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

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

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

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

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

通話が会議に移動されると、音声ファイルの再生が停止します。

DTMF のキャプチャと送信 [#capture-and-send-dtmf-understanding-calls-api]

DTMF(Dual-Tone Multi-Frequency)を介してユーザーまたはリモートシステムと対話するには、関連するcapture および sendメソッドを使用します。

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

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

エンドユーザーはw、W の文字のみを含む DTMF 入力を送信できます： 0-9, w, W.

自動機械検出 [#automated-machine-detection-understanding-calls-api]

PHONE宛先への新しい発信コールを作成し、machineDetectionオプションを有効にして、自動マシン検出(AMD)を実行するようにアプリケーション要求を設定します。

コールで AMD を実行するために、次の 2 つのオプション パラメータを設定できます。

1. 検出時間: AMD は通常、人間が応答したか機械が応答したかを判断するために 3.74 秒の音声を必要とします。検出時間パラメータを使用して分析時間を調整できます。次に例を示します。
   • 検出時間が短い(わずか1秒)ため、ボイスメールのピックアップをすばやく識別できます。
   • 検出時間が長くなると(最大「5秒」)、人間と機械の識別精度が向上します。
2. メッセージ検出タイムアウト: このパラメーターは、留守番電話が検出されたときにメッセージのアナウンスの終わりを検出するための最大時間を示します。これを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イベントを受け取った後、アプリケーションはその呼び出しをさらに進める方法を決定する必要があります。

レコーディング [#recordings-understanding-calls-api]

レコーディングは、通話、会議およびダイアログで使用でき、相互に排他的です。

通話のレコーディング [#recording-calls-understanding-calls-api]

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

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

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

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

会議やダイアログのレコーディング [#record-conferences-and-dialogs-understanding-calls-api]

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

• 新しい会議またはダイアログが作成された時にレコーディング (オーディオまたはオーディオとビデオの両方) をアクティブにする
• 会議レコーディング開始API または または ダイアログ記録の開始 API メソッド を使って、レコーディングを明示的に開始する

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

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

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

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

オンデマンドのレコーディングコンポジション [#on-demand-recording-composition-understanding-calls-api]

録音の作成を明示的に要求せずに会議またはダイアログを録音する場合 (つまり、すべての参加者トラックが混在している 1 つのファイルのみを録音する場合)、録音は複数のオーディオ ファイルまたはビデオ ファイルになります (会議またはダイアログがアクティブなときに Start/Stop レコーディング アクションごとに参加者ごとに 1 つ)。

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

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

マルチチャンネル録画 [#multichannel-recordings]

ダイアログまたは会議のオンデマンド コンポジションをリクエストする場合、作成されるコンポジション メディア ファイルをマルチチャンネルにするように要求できます。その場合、ダイアログまたは会議の各参加者は個別のオーディオ チャネルに分離されます。

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

• 個々の参加者が言ったことの明確で議論の余地のない証拠を提供するなど、法的およびコンプライアンスの状況。
• 文字起こしと分析:一部の文字起こしツールは、適切な話者のダイアライゼーションをサポートしておらず、各話者を別々のチャネルに分離する必要があります。
• マルチチャンネル録音は、オンデマンドコンポジションでのみ利用できます。

レコーディング結果の表示とダウンロード [#view-and-download-recordings-understanding-calls-api]

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

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

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

1. Voiceチャンネルアプリケーションの下の録音タブに移動します。
2. [通話]、[会議]または [ダイアログ] を選択して、レコーディング結果の一覧を表示します。
3. 特定の録音エントリを展開すると、作曲済みか作曲済みかに関係なく、関連ファイルのリストが表示されます。クラウドストレージに保存されているファイルは、関連するメタデータjsonファイルと同様にダウンロードできます。

レコーディング結果のカスタムメタデータの設定 [#setting-custom-metadata-on-your-recordings-understanding-calls-api]

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

レコーディングファイル名の命名規則 [#recording-filename-convention-understanding-calls-api]

レコーディングした通話、会議またはダイアログのファイル名は、合成済みか未合成かに関わらず、常に fileId.ext です。拡張子のext は、レコーディング結果がオーディオのみの録音かビデオのみを録画かによって、wav または mp4 に変わります。

SFTP経由のレコーディング結果の転送 [#transfer-recordings-via-sftp-understanding-calls-api]

レコーディングをSFTP経由でサーバーにプッシュする場合は、NTT CPaaS UI から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 になります。必ず一意のプレフィックスを使用してください。

WebSocket ストリーミング [#media-streaming-understanding-calls-api]

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

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

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

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

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

2. WebSocket エンドポイント

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

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

ストリーミング メディア アクション [#streaming-media-action]

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

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

メディア置換無しのストリーミング [#streaming-without-media-replacement-understanding-calls-api]

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

メディア置換によるストリーミング [#streaming-with-media-replacement-understanding-calls-api]

次に、上記と同じ例を使って、外部ホストがオーディオフィルタリング(ボイスチェンジャー、冒涜フィルターなど)といったサービスを提供する役割を担う場合について説明します。この場合、改良されたオーディオが会議に挿入され、それがこの会議のすべての参加者に聞こえるようになります。

メディア・ストリーミング構成の作成 [#create-media-streaming-configuration-understanding-calls-api]

まず、メディア ストリーム構成オブジェクトを作成します。このオブジェクト内では、WebSocket ホストの URL と、それにアクセスするために必要な承認 (存在する場合) を指定する必要があります。

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

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

すべてが成功した場合、ホストが受信する最初のメッセージは次のとおりです。

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

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

着信オーディオストリームの解析 [#parsing-incoming-audio-streams-understanding-calls-api]

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

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

オーディオは生でストリーミングされ、各オーディオサンプルは 16 ビット符号付き整数としてエンコードされ、2 バイト値として表されます。つまり、すべての着信メッセージには 1920 バイト (960x2) が含まれているのが理想的です。但し、ネットワークに問題がある場合は、メッセージ内で複数のパケットが送信される可能性があります。これらのパケットは、1920 バイトの倍数(3840、5760、7680 など)であることが保証されています。

メディア置換 [#media-replacement-understanding-calls-api]

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

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

WebSocket エンドポイント

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

• 複数の参加者が参加する会議。
• 参加者が 1 人のダイアログ。

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

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

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

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

WebSocket エンドポイントを接続する

WEBSOCKETコールレッグは、 create call、 connect with new call、 add new call、 create dialogなどのメソッドで開始できます。種類が WEBSOCKET のアウトバウンド呼び出しを作成する場合は、WebSocket 構成 ID を指定します。

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

WebSocket メッセージ

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

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

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

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

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

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

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

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

一括通話 [#bulk-calls-understanding-calls-api]

一括 API メソッドを使用すると、1 つの要求で複数の通話を作成し、スケジュールされた一括通話を管理できます。一括メソッドで生成された通話は、自動機械検出、レコーディング、複数のエンドポイントタイプ(電話、webRTC、SIP、Viber)のサポートなど、単一の通話と同じオプションをサポートします。一括呼び出しは、PHONE 宛先に対してのみ作成できます。

一括通話では、次のような追加パラメータがサポートされます。

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

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

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

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

宛先への接続が成功した場合、通話が完了した後でのみ BULK_STATUS_EVENT が送信されます

WebRTCを使った通話

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

• バックエンドアプリケーションからのWebRTC呼び出しを包括的かつきめ細かく制御します。
• 会議へのWebRTC通話への参加とWebRTC通話の削除が簡単にできます。
• webRTCコールを、サポートされている他のエンドポイント(電話、SIP)と同じ会議に混在させます。
• バックエンドアプリケーションにインバウンドWebRTCコールのルーティングロジックを実装します。
• webRTC通話では、テキスト読み上げの再生、DTMFの収集と送信、オーディオファイルの再生が可能です。

通話にwebRTCを使用するには、次のことを行う必要があります。

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

コールAPIとCPaaSX

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

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

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

発信通話での ApplicationId と EntityId

発信通話でCPaaSXのapplicationIdやentityIdを設定するには、以下のメソッドを使用し、プラットフォームオブジェクトにapplicationIdやentityIdの値を設定します：

• コールの作成
• コールの一括作成

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

• 新しい通話に接続する
• ダイアログの作成

着信通話での ApplicationId と EntityId

番号の音声設定で指定されているapplicationIdやentityIdでフラグが立てられた着信コール(この設定が API によって定義されている場合、または Web インターフェイスの Numbers アプリケーションの受信設定を介して)。

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

CPaaSXのapplicationIdやentityIdが着信通話や発信通話に定義されている場合、これらのapplicationIdやentityIdが反映されます：

• その呼び出しに関連するすべての呼び出し API イベント。
• Web インターフェイスから生成およびダウンロードされた詳細な 音声レポート 。
• ß、会議、およびダイアログ履歴 CDR を呼び出します。
• 通話、 会議、および ダイアログ は 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 も定義されているかどうか、また定義されている場合はその値によって異なります。

トラブルシューティング

エラーの確認 [#checkerrors-troubleshooting]

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

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

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

ライブ通話と会議の確認 [#check-live-calls-and-conferences-troubleshooting]

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

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

履歴ログとレポートの確認 [#check-historical-logs-and-reports-troubleshooting]

Web インターフェイスから [#from-the-web-interface-troubleshooting]

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

APIの使用 [#useapi-troubleshooting]

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

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