Voice Gateway からの発着信詳細記録レポート・イベント

IBM® Voice Gateway は、発着信詳細記録 (CDR) イベントを生成できます。このイベントには、単一の通話に関する要約情報が含まれます。 これらのイベントは、Voice Gateway からの HTTP POST 要求として、イベントを保管するSplunk HTTP Event Collector (HEC) または REST サーバーに統合しやすい形式で送信されます。 バージョン 1.0.0.5d 以降では、CDR イベントを直接 IBM Cloudant にパブリッシュするよう Voice Gateway を構成することもできます。

• 発着信詳細記録イベントをパブリッシュするための Voice Gateway の構成
• CDR イベントを IBM Cloudant データベースにパブリッシュするための Voice Gateway の構成
• CDR イベントを CouchDB にパブリッシュするための Voice Gateway の構成
• 発着信詳細記録イベントのフォーマット
• 発着信詳細記録イベントへのカスタム値の注入

発着信詳細記録イベントをパブリッシュするための Voice Gateway の構成

1. 例えば noSQL データベースなどに、イベントを保管できるよう Splunk HTTP Event Collector (HEC) または REST サーバーをセットアップします。 『CDR イベントを IBM Cloudant データベースにパブリッシュするための Voice Gateway の構成』を参照してください (このいずれかを使用してイベントを保管する場合)。

2. Voice Gateway 構成で、REST サーバー URL および許可資格情報を指定し、発着信詳細記録 (CDR) イベント・インデックス値を設定することで、発着信詳細記録イベントを有効にします。

   • シングル・テナント環境: 構成に以下の環境変数を設定します。

     REPORTING_URL=http://myresteventserver.ibm.com/
     REPORTING_USERNAME=myRestAdmin
     REPORTING_PASSWORD=myRestTokenOrPassword
     REPORTING_CDR_EVENT_INDEX=cdr
     

   • マルチテナント JSON 構成: マルチテナント JSON 構成ファイルで、発着信詳細記録イベントを有効にする各テナントに、以下のプロパティーを含む reporting オブジェクトを構成します。 同じオブジェクト内で、transcription イベントや Watson Assistant turn イベントなどの他のタイプのイベントに対するインデックスを構成できます。

     ...
     "reporting": {
      "url": "http://myresteventserver.ibm.com/",
      "username": "myRestAdmin",
      "password": "myRestTokenOrPassword",
      "cdrEventInd": "cdr"
     }
     ...
     

   CDR イベント・インデックス値が、すべての発着信詳細記録イベントで index 値として含まれるため、それらのイベントを取り込む REST サーバーは、イベントのタイプを識別できます。 インデックス・フィールドは Splunk HEC には必須ですが、これらのイベントを処理するために独自の REST サーバーを作成するユーザーにも役立ちます。

CDR イベントを IBM Cloudant データベースにパブリッシュするための Voice Gateway の構成

データベースにパブリッシュするよう Voice Gateway を構成する前に、IBM® Cloudant® for IBM Cloud をセットアップしてください。

CDR イベントを IBM Cloudant データベースにパブリッシュするため、構成に以下の環境変数を設定します。 構成に IBM Cloudant 構成変数を追加することによって、IBM Cloudant および別のレポート・サービスの両方を同時に使用できます。 IBM Cloudant に対する認証を、REPORTING_CDR_CLOUDANT_APIKEY 変数を追加することによって API 鍵で行うように構成するか、または、REPORTING_CDR_CLOUDANT_USERNAME と REPORTING_CDR_CLOUDANT_PASSWORD を追加することによってユーザー名とパスワードで行うように構成することができます。

以下の例は、CDR イベントを IBM Cloudant にパブリッシュするための構成を示しています。

• シングル・テナント環境: 構成に以下の環境変数を設定します。

  REPORTING_CDR_CLOUDANT_URL =http://mycdrcloudant.ibm.com/
  REPORTING_CDR_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
  REPORTING_CDR_CLOUDANT_USERNAME=myCloudantUsername
  REPORTING_CDR_CLOUDANT_PASSWORD=myCloudantPassword
  REPORTING_CDR_CLOUDANT_DB_NAME=myCloudantDB
  REPORTING_CDR_CLOUDANT_EVENT_INDEX=cdr
  

  IBM Cloudant に対して、デフォルト以外のアカウント構成を使用する場合、追加の環境変数の組み込みが必要になる場合があります。 『レポート・イベント構成』で REPORTING_CDR_CLOUDANT_URL および REPORTING_CDR_CLOUDANT_ACCOUNT を参照してください。

• マルチテナント JSON 構成の使用: マルチテナント JSON 構成ファイルで、発着信詳細記録イベントを有効にする各テナントに、以下のプロパティーを含む reporting オブジェクトを構成します。 IBM Cloudant に対して、デフォルト以外のアカウント構成を使用する場合、追加の環境変数の組み込みが必要になる場合があります。 『reporting オブジェクトのプロパティー』で cdrCloudant を参照してください。

  ...
  "reporting": {
    "cdrCloudant": {
      "url": "http://mycdrcloudant.ibm.com/",
      "username": "myCloudantUsername",
      "password": "myCloudantPassword",
      "apiKey": "myApiKey",
      "dbName": "myCloudantDB",
      "eventInd": "cdr"
    }
  }
  ...
  

認証用の API 鍵の使用

IBM Cloudant 資格情報のユーザー名とパスワードの組み合わせを使用する代わりに、認証に API 鍵を使用することができます。 IBM Cloudant に対するサービス資格情報を検索または生成し、その後で、URL および API 鍵の値を Voice Gateway レポート・イベント構成にコピーできます。 API 鍵について詳しくは、IBM Cloudant: API keys を参照してください。

以下の API 鍵認証の例は Cloudant に対して機能します。 CouchDB への認証に API 鍵を使用することはできません。

• シングル・テナント環境: 構成に以下の環境変数を設定します。

  REPORTING_CDR_CLOUDANT_URL=http://mycdrcloudant.ibm.com/
  REPORTING_CDR_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
  REPORTING_CDR_CLOUDANT_DB_NAME=myCloudantDB
  REPORTING_CDR_CLOUDANT_EVENT_INDEX=cdr
  

• マルチテナント JSON 構成: username と password の代わりに、url と apikey の構成変数を構成する必要があります。

  ...
  "reporting": {
  "cdrCloudant": {
    "url": "http://mycdrcloudant.ibm.com/",
    "apikey": "a1b2c3d3fgh1jk1mn0",
    "dbName": "myCloudantDB",
    "eventInd": "cdr"
  }
  }
  ...
  

CDR イベントを CouchDB にパブリッシュするための Voice Gateway の構成

CouchDB をセットアップするには、リポジトリーを複製し、Github にある指示に従います。 CouchDB を使用する場合は、認証のために API 鍵を使用することはできません。

CDR イベントを IBM Cloudant データベースにパブリッシュするため、構成に以下の環境変数を設定します。 構成に IBM Cloudant 構成変数を追加することによって、IBM Cloudant および別のレポート・サービスの両方を同時に使用できます。

以下の例は、CDR イベントを CouchDB にパブリッシュするための構成を示しています。

• シングル・テナント環境: 構成に以下の環境変数を設定します。

  REPORTING_CDR_CLOUDANT_URL="http://<svc-couchdb>:5984/"
  REPORTING_CDR_CLOUDANT_USERNAME=myCouchDBUsername
  REPORTING_CDR_CLOUDANT_PASSWORD=myCouchDBPassword
  REPORTING_CDR_CLOUDANT_DB_NAME=myCouchDB
  REPORTING_CDR_CLOUDANT_EVENT_INDEX=cdr
  

• マルチテナント JSON 構成の使用: マルチテナント JSON 構成ファイルで、発着信詳細記録イベントを有効にする各テナントに、以下のプロパティーを含む reporting オブジェクトを構成します。 IBM Cloudant に対して、デフォルト以外のアカウント構成を使用する場合、追加の環境変数の組み込みが必要になる場合があります。 『reporting オブジェクトのプロパティー』で cdrCloudant を参照してください。

...
"reporting": {
  "convCloudant": {
    "url": "http://<svc-couchdb>:5984/",
    "username": "myCouchDBUsername",
    "password": "myCouchDBPassword",
    "dbName": "myCouchDB",
    "eventInd": "cdr"
  }
}
...

発着信詳細記録イベントのフォーマット

発着信詳細記録 (CDR) イベントには、単一の通話に関する要約情報が含まれます。 イベントのフォーマットは、Splunk HTTP Event Controller JSON フォーマットに基づきます。

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18595552498",
"sourcetype": "e164",
"index": "cdr",
"event": {
  "version": "1.0",
  "sipCallID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "globalSessionID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "initTime": 1520877996309,
  "startTime": 1520877998461,
  "stopTime": 1520878020781,
  "setupTime": 2152,
  "callLength": 22320,
  "sipToURI": "sip:+18445555174@169.46.147.46",
  "sipFromURI": "sip:+18595553171@vgwdemo.pstn.twilio.com",
  "maxSTTTransaction": 1212,
  "endReason": "failed",
  "failureDetails": "details on why call failed",
  "failureOccurred": true,
  "echoDetected": false,
  "transferTarget": "sip or tel URI",
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ],
  "warnings": [
    {
      ...
    }
   ],
  "rtpNetworkSummary": {
     ...
  }
}
}

イベント・メタデータ

すべてのレポート・イベントは、以下のメタデータから開始します。

発着信詳細記録イベント・オブジェクト

発着信詳細記録イベントの event JSON オブジェクトには、以下のキーが含まれます。

Watson Assistant 詳細

conversations オブジェクトには、通話中に使用されたすべての Watson Assistant セッションが含まれます。

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18885553333",
"sourcetype": "e164",
"index": "cdr",
"event": {
  "version": "1.0",
  "sipCallID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "globalSessionID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "initTime": 1520877996309,
  "startTime": 1520877998461,
  "stopTime": 1520878020781,
  "setupTime": 2152,
  "callLength": 22320,
  "sipToURI": "sip:+18445555174@169.46.147.46",
  "sipFromURI": "sip:+18595553171@vgwdemo.pstn.twilio.com",
  "numberOfBargeins": 0,
  "maxConvTransaction": 1447,
  "maxTTSTransaction": 616,
  "endReason": "failed",
  "failureDetails": "details on why call failed",
  "failureOccurred": true,
  "echoDetected": false,
  "transferTarget": "sip or tel URI",
  "customCDRData" :  {
    "key1": "value1",
    "key2": "value2"
  },
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ],
  "warnings": [
    {
      ...
    }
   ],
  "rtpNetworkSummary": {
     ...
  }
}
}

通話で使用された各会話の JSON オブジェクトには、以下のキーが含まれています。

警告の詳細

warnings オブジェクトには、通話中にログに記録された警告が含まれます。これらの警告は、発行された順番にリストされます。 以下の条件の警告が含まれます。

• 発話が信頼度スコアのしきい値によって除外されたときのメッセージ。
• Text to Speech のアンダーフロー。これは、テキストから音声への合成が Voice Gateway のストリーミング速度に追いつかず、音声がスキップされる場合があるときに発生します。
• 高いパケット損失率、高い平均ジッターなど、RTP ネットワーク警告 (RTCP が有効化されている場合)。

"warnings": [
 {
   "timestamp": "2018-02-08T13:03:01Z",
   "message": "CWSMR0032W: A Watson Speech to Text final utterance has a confidence score of 0.1, which does not meet the confidence score threshold of 0.2. The utterance will be ignored.",
   "id": "CWSMR0032W"
 },
 {
   "timestamp": "2018-02-08T13:10:01Z",
    "message": "CWSMR0031W: The synthesis stream from the Watson Text To Speech service can't keep up with the playback rate to the caller, so audio might skip. transaction ID=a1b2c3d4e5",
    "id": "CWSMR0031W"
 }
]

各警告のオブジェクトには、以下のキーが含まれます。

RTP ネットワーク・サマリーの詳細

RTCP が有効化されている場合、各 rtpNetworkSummary オブジェクト内の inboundStream オブジェクトでインバウンド・ストリームの統計が提供され、outboundStream オブジェクトでアウトバウンド・ストリームの統計が提供されます。

"rtpNetworkSummary": {
  "inboundStream": {
      "maxJitter": 5,
      "averageJitter": 1,
      "packetsLost": 0,
      "totalPackets": 1000,
      "canonicalName": "user@example.com",
      "toolName": "User SIP Phone"
   },
  "outboundStream": {
      "maxJitter": 5,
      "averageJitter": 1,
      "packetsLost": 0,
      "totalPackets": 2000,
      "canonicalName": "voice.gateway@127.0.0.1",
      "toolName": "IBM Voice Gateway/1.0.0.5"
   }
}

各ストリームのオブジェクトには、以下のキーが含まれます。

発着信詳細記録イベントへのカスタム値の注入

vgwActAddCustomCDRData を Watson Assistant ダイアログまたは SOE に含めることにより、カスタム・データを発着信詳細記録に追加することができます。 通話中に発生しているさまざまなアクティビティーに関連したデータを記録できます。 これには、特定のタスクの完了を識別する方法が含まれます。

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

CDR レポートを生成しているときに、カスタム・データが customCDRData フィールドに含まれます。 例えば、以下の CDR レポートでは、key1 と key2 が customCDRData フィールドに追加されます。

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18881112222",
"sourcetype": "e164",
"index": "cdr",
"event": {
  ...
  "customCDRData" :  {
    "key1": "value1",
    "key2": "value2"
  },
  "conversations": [
    {
      "id": "1234",
      ...
    }
  ]
}
}

CDR データのマージ

通話中、vgwActAddCustomCDRData アクションが複数回アクティブにされると、データが customCDRData フィールドにマージされます。

最初の通話で、key1 と key2 の値が定義されます。

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

2 番目の通話で、key1 と key3 の値が定義されます。

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value11",
    "key3": "value3"
  }
}

以下のコード例は、これらの通話の後、カスタム CDR データが customCDRData フィールドでどのようにマージされるかを示しています。ここで、key1 の値 value11 は、2 番目の通話からのものです。

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18595552498",
"sourcetype": "e164",
"index": "cdr",
"event": {
  ...
  "customCDRData" :  {
    "key1": "value11",
    "key2": "value2",
    "key3": "value3"
  },
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ]
}
}

カスタム CDR データの削除

CDR カスタム・データを削除するために、SOE は、"" にキーを設定して vgwActAddCustomCDRData アクションを発行します。

以下の例は、key1 フィールドをカスタム CDR データから削除するために、key1 値をブランク "" で上書きすることを示しています。

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": ""
  }
}