呼び出し API とは

通話は開発者向けに設計された音声機能で、 API を通じてのみ利用できます。

呼び出しを使用して、着信呼び出しと送信呼び出しを処理する任意のアプリケーションを作成できます。アプリケーションは、音声シナリオ ロジックを実装し、通話 API を使用して通話と会議のアクションを制御および実行し、選択した音声チャネル (PSTN、webRTC、SIP) を介して実行します。

電話番号マスキング、 Click-to-Call、 Voice Message、または Interactive Voice Response とは異なり、アプリケーションは特定のユースケース シナリオにバインドされません。通話 API は、あらゆる音声アプリケーションの構成要素です。

呼び出し API で次の機能を使用するには、アカウントでこれらを有効にする必要があります。

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

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

コンセプト

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

• 通話設定
• 数字
• APIの呼び出し
• Events

コール設定 [#calls-configuration]

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

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

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

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

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

• サブスクリプションの作成: 最初の手順は、少なくとも 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プラットフォームが自動的にインバウンドコールに応答し、ブリッジします。
• コールレッグでのアクション: ダイアログを使用してコールレッグに参加する場合、メディア(オーディオファイルまたは音声合成)を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 エンドポイント タイプでは、少なくとも ID*、*呼び出されるエンド ユーザーを指定する一意の識別子を指定する必要があります。
3. SIP: アプリケーションは、セッション開始プロトコル (SIP) を使用して、オフィスの PBX (オンプレミスまたはクラウド) に接続されているユーザーに電話をかけることができます。SIP エンドポイントを呼び出すには、少なくとも username、host、および port を宣言する必要があります。SIP エンドポイントへの通話を作成する前に、通話 API の SIP トランク メソッドを使用して、NTT CPaaS とオフィス PBX 間の SIP トランクを定義する必要があります。
4. VIBER:Viberユーザーからの着信コールはVIBERタイプで、発信元のViberユーザーのMSISDNが含まれます。Viberユーザーからの電話の受信の詳細については、Viberビジネスコールを参照してください。

PHONE エンドポイントと SIP エンドポイントにコールを発信する場合、着信側に表示される発信者 ID を指定できます。発信者IDは、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を含めます。
• ウェブインターフェース経由:
  • Numbersアプリケーションに移動し、番号を選択します。
  • [Voice] タブを選択します。
  • 転送アクションが サブスクリプションに転送 である受信設定を作成し、callsConfigurationIdを指定します。

新しい通話を受信すると、アプリケーションは通話の ID (callId) と 宛先 および 送信元 の電話番号を含む CALL_RECEIVED イベントを受信します。送信呼び出し方法を使用して明示的に送信しない限り、呼び出し元には呼び出し音は聞こえません。次に、アプリケーションは独自のロジックに基づいて、呼び出しを拒否するか、事前応答するか、または応答するかを決定できます。呼び出しを受け入れることを決定した場合は、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のステータスを含むイベントをアプリケーションのイベントWebhookに送信します。

CALL_ESTABLISHED イベントを受信すると、アプリケーションは NTT CPaaS プラットフォームから通話がライブであることを確認し、アプリケーションは次のステップに進むことができます。アプリケーションが CALL_FAILED または CALL_FINISHED イベントを受信した場合、そのイベントのペイロードを検査して、呼び出しの状態と呼び出しの終了または失敗の原因に関する詳細を取得します。

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

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

次の呼び出しフローは、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 つの通話を接続する最も一般的な方法は次のとおりです

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

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

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

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

通話 API 会議では、アプリケーションで同じ会議室に最大 15 人の参加者を追加できます。会議は複数のエンドポイントを同時にサポートするため、同じ会議の参加者は電話(PSTN)、webRTC(ビデオの有無にかかわらず)、および SIP を介して参加できます。

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

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

次の会議フローでは、既存の通話を会議に追加し、エンドユーザー A とエンドユーザー B への通話が既にライブであることを前提としています。会議は最初に作成する必要があり、一意の conferenceId を含む CONFERENCE_CREATED イベントによって確認されます。参加者を呼び込むには、エンド ユーザー A とエンド ユーザー B の通話からの conferenceId と一意の 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 メソッドを使用して、そのアプリケーションによって管理される任意の呼び出しでテキスト読み上げアクションを実行できます。NTT CPaaSは、100以上の言語とアクセントをサポートしています。

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

• 言語コードは、選択した言語の 2 文字の省略形です。
• 音声性別は男性または女性です。
• VoiceName は音声の名前です。

NTT CPaaS プラットフォームは、アプリケーションの イベント Webhook に 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イベントで報告され、次のものが含まれます。

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

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

通話の文字起こしは、通話時間自体 (つまり、通話が終了したとき、または通話が会議に移動されたとき) によって制限されません。文字起こしは API メソッドを介して開始および停止されます。アプリケーションには、タイプ TRANSCRIPTION のイベントを含むサブスクリプションが必要です。

通話の文字起こしを開始するときに、INTERIM トランスクリプトと COMPLETE トランスクリプトの両方を受信するか、COMPLETE トランスクリプトのみを受信するかを選択できます。

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

アプリケーションは、個々の通話または会議中にいつでもオーディオ ファイルを再生できます。会議中にファイルが再生されると、すべての参加者にそのファイルが聞こえます。

音声ファイルは、再生時にURLから取得するか、NTT CPaaSサーバーに先にアップロードすることができます。NTT CPaaSサーバーから音声ファイルを再生するには、まずPOST /calls/1/file/upload方式でそのファイル(.wavまたは.mp3)をアップロードする必要があります。アップロード アクションは、play アクションで指定する必要がある fileId を返します。

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

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

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

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

PLAY_FINISHED イベントは常に生成されます。

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

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

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

再生方法中の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) を介してユーザーまたはリモート システムと対話するには、関連する キャプチャ および 送信 メソッドを使用します。

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

1. 明示的には、テキスト読み上げファイルまたはオーディオ ファイルの再生中です。text to speech または オーディオ ファイルの再生 の使用に関する上記のセクションで、stopOn パラメーターの使用法について説明します。この場合、DTMF コレクションの最大長は 1 桁です。このシナリオでは、収集された DTMF は、対応する PLAY_FINISHED または SAY_FINISHED イベントで返されます。
2. 明示的には、 キャプチャ DTMF メソッドを使用します。任意のサイズの DTMF 入力を収集し、オプションで終端文字を定義できます。maxLength パラメーターのみを定義すると、プラットフォームは、ユーザーがそのサイズの入力を入力するか、タイムアウトに達するまで待機します。ターミネーター・パラメーターを設定すると、エンド・ユーザーによってユーザーが入力された場合、プラットフォームは定義された maxLength よりも短いユーザー入力を返すことがあります。 このシナリオでは、収集された DTMF 入力が DTMF_COLLECTED イベントで返されます。
3. 未承諾: 保留中の キャプチャ 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 (失敗した場合)。

音声メッセージやクリック・トゥ・コールなどの他の音声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 録画のリストを取得するときに参照されたままになります。

デフォルトでは、SFTP サーバーにプッシュされる通話API録音の命名規則は fileId.zip です。zipファイルには、メディアファイル(wavまたはmp4)と、その録音に関連するメタデータを含む対応するjsonファイルの両方が含まれます。zip アーカイブ内のファイルには、fileId パラメーターで名前が付けられます。

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

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

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

呼び出し API は、次の 2 つの異なる WebSocket ストリーミング オプションをサポートしています。

• ストリーミングメディアアクション: 特定のコールレッグから外部サービスへのオーディオストリームを複製(フォーク)し、元のオーディオを置き換えるオプションがあります。1 つの通話レッグでの文字起こし、感情分析、または音声フィルタリングに適しています。
• WebSocket エンドポイント:外部メディア処理サービスを、会議またはダイアログの個別の参加者として追加します。会話型 AI 音声ボット、話者のダイアライゼーション、録音、またはすべての参加者のブロードキャストに適しています。

もっと詳しく知る

両方の統合オプションの設定手順、オーディオコーデックの仕様、およびメッセージ形式については、WebSocket ストリーミングの使用を参照してください。

一括通話 [#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 が送信されます