コール

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

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

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

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

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

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

コンセプト

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

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

コール設定

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

コール構成の作成

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

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

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

• サブスクリプションの作成: 最初の手順は、少なくとも 1 つのイベント サブスクリプションを作成することです。サブスクリプションは、Infobip Web インターフェイスまたは API で作成および管理できます。
  1. チャネルの種類を指定する: イベント サブスクリプションを設定するときに、チャネルの種類をVOICE_VIDEOとして指定します。これにより、アプリケーションが処理するイベントの性質が定義されます。
  2. プロファイルの定義: サブスクリプションのプロファイル セクションには、アプリケーションの Webhook の詳細を含める必要があります。これには、Webhook の URL とセキュリティ仕様が含まれ、安全でダイレクトな通信が保証されます。
  3. 目的のイベントを一覧表示する: サブスクリプションの events 配列で、Webhook に送信するすべての Calls API イベントを一覧表示します。これらは、アプリケーションの機能に関連するすべてのイベントを含むコンマ区切りのリストとして指定する必要があります。考えられるすべての呼び出し API イベントの一覧は、 イベント Webhook (opens in a new tab) にあります。
  4. 条件オブジェクトの設定: 最後のステップは、サブスクリプションの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 音声番号をアプリケーションにリンクするには、FORWARD_TO_SUBSCRIPTIONアクションとcallsConfigurationIdを併用して API (opens in a new tab) を使用する必要があります。

コール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 エンドポイントに通話できるようになるには、少なくとも ユーザー名、ホスト、ポートを宣言する必要があります。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経由：
  • Infobip 番号で、アクション タイプ FORWARD_TO_SUBSCRIPTION を使用して音声設定を作成し (opens in a new tab)、callsConfigurationIdを含めます。
• Webインターフェイス経由：
  • Numbersアプリケーション (opens in a new tab)に移動し、番号を選択します。
  • [Voice] タブを選択します。
  • 転送アクションが サブスクリプションに転送 である受信設定を作成し、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 イベント)を受信した後、アプリケーションはconnectメソッドを使ってコールを接続し、両コールの一意の 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 eveイベントによって確認されます。参加者を呼び込むには、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)を確認するイベントを受信します。

会議の役割

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

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

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

役割の割り当て

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

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

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

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

役割の移行

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

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

1. PARTICIPANT_ROLE_CHANGED
2. PARTICIPANT_ROLE_CHANGE_FAILED

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

テキスト読み上げ

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

sayリクエストペイロードを定義する時は、この TTSテーブル を参照してください。

• 言語コードは、選択した言語の 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 メソッドを使用します。

音声テキスト変換

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

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

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

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

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

音声キャプチャ

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

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

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

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

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

• 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 はどちらも、オーディオファイルを初めて再生する時に適用されます。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. 検出時間: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 とは異なり、Infobip プラットフォームは、マシンが通話に応答したことを検出しても特定のアクションを実行しません。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. [コール]、[カンファレンス]または [ダイアログ] を選択して、レコーディング結果の一覧を表示します。
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 になります。必ず一意のプレフィックスを使用するようにしてください。

WebSocket ストリーミング

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

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

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

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

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

2. Websocket エンドポイント

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

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

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

呼び出し 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 バイト (960x2) が含まれているのが理想的です。但し、ネットワークに問題がある場合は、メッセージ内で複数のパケットが送信される可能性があります。これらのパケットは、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コールレッグは、 create call (opens in a new tab)、 connect with new call (opens in a new tab)、 add new call (opens in a new tab)、 create dialog (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 インターフェイスで現在サポートされているオーディオ コーデックは Linear PCM 16 ビットで、サンプル レートは 8kHz または 16kHz、フレーム サイズは 20ms です。

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

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

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

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

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

一括コール

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

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

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

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

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

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

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

CallsにWebRTCを使用

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

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

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

• webRTC はじめに セクションの手順に従って、webRTC アプリケーションを宣言します。
• Infobip webRTC SDK を Web またはモバイル (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)に記載されているように、Calls APIプラットフォームに関連する特定のガイドラインに従ってください。

コールAPIとCPaaSX

Calls APIプラットフォームはNTT CPaaS CPaaSXをサポートしています。特に、Calls 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 によって定義されている場合、または Web (opens in a new tab) インターフェイスの Numbers アプリケーションの受信設定を介して)。

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

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

• その呼び出しに関連するすべての呼び出し API イベント。
• Web インターフェイスから生成およびダウンロードされた詳細な 音声レポート (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)、および ダイアログ (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 リクエストのフィルタリングが可能になります。