Voice Interaction Resource API

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：34分

    • 音声インタラクション API は、電話での会話中にエージェントと発信者の間の音声インタラクションを文字起こしして保存するためのエンドポイントを提供します。仮想エージェントチャットやライブエージェントチャットと連携して機能します。

    この API を使用して、進行中の通話から文字起こしされたメッセージをリアルタイムで保持したり、既存の音声会話録音を履歴目的で文字起こしして保存したりできます。文字起こしされたメッセージは エージェントワークスペース で表示されるため、エージェントは発信者と話しながら、エージェントアシストや検索などの機能を活用できます。文字起こしされたメッセージは、会話メッセージ [sys_cs_message] テーブルに保存されます。

    エージェントワークスペースでメッセージを文字起こし

    フローを呼び出す

    次のコールフローは、 音声インタラクション API を使用して音声インタラクションレコードを作成し、その音声会話内のメッセージを文字起こしして保存してから、音声会話レコードを閉じる方法を示しています。ビジネスルールやその他のスクリプトを使用してこの機能を実行することもできますが、このタイプの実装については、このセクションでは説明しません。
    1. まず、 音声インタラクションリソース - POST /cs/voice-interactions エンドポイントを呼び出して、インタラクション [interaction] テーブルに音声インタラクションレコードを作成します。
    2. 次に、 音声インタラクションリソース - POST /cs/voice-interactions/{interactionId}/messages エンドポイントを呼び出して、音声会話からの翻訳されたメッセージを会話メッセージテーブルに保存します。リアルタイム会話を処理している場合は、メッセージが適切なタイミングで エージェントワークスペース 表示されるように、このエンドポイントを頻繁に呼び出す必要があります。履歴目的で記録を処理する場合は、1 回のエンドポイント呼び出しですべてのメッセージを渡すことができます。
    3. 音声メッセージの永続化が完了したら、 音声インタラクションリソース - PATCH /cs/voice-interactions/{interactionId}/state エンドポイントを呼び出してキャプチャを終了し、音声インタラクションレコードを閉じます。

    可用性

    この API はベース ServiceNow システムで利用できます。アクセスは、インタラクション [interaction] テーブルと会話 [sys_cs_conversation] テーブルに課せられる ACL によって制限されます。

    音声インタラクションリソース - PATCH /cs/voice-interactions/{interactionId}/state

    指定された音声インタラクションを終了します。いったん呼び出されると、追加のボイス メッセージは翻訳されず、電話での会話用に保存されません。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/state

    デフォルト URL: /api/now/v1/cs/voice-interactions/{interactionId}/state

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    interactionId 音声インタラクションを終了するインタラクションレコードのSys_id。音声インタラクションリソース - POST /cs/voice-interactions エンドポイントによって渡されます。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    recordingURL 元の音声録音がある URL。

    そのように構成されている場合、この URL が エージェントワークスペース に表示されます。

    データタイプ：文字列

    デフォルト：なし
    状況 必須。音声インタラクションのステータス。

    サポートされている値:closed_complete

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。JSON の形式が正しくないか、必須パラメーターが渡されませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 操作のステータス。
    可能な値：
    • 成功
    • 失敗

    エラーが発生した場合は、エラーを説明するメッセージも返されます。エラーが ServiceNow インスタンスにある場合、インスタンスは関連するスタックトレースをログに記録します。

    cURL 要求

    次の例は、音声インスタンスを終了する方法を示しています。

    curl "http://instance.servicenow.com/api/now/v1/ cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/state" \ 
--request PATCH \
--header "Content-Type: application/json" \
--header "Accept:application/json" \
--user 'username':'password' \
-d {
  "state": "closed_complete",
  "recordingURL": "https: //zoom_instance/rec/QbF7XmPFHPlX1LG"
}’

    応答：

    {
  "result": "Success"
}

    音声インタラクションリソース - POST /cs/voice-interactions

    インタラクション [interaction] テーブル内に音声インタラクションレコードを作成します。

    文字起こしされたボイスメッセージを保存する前に、このレコードを作成する必要があります。このエンドポイントを使用して、特定のユーザー ID を渡して特定のエージェントにコールを割り当てることもできます。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/cs/voice-interactions

    デフォルト URL: /api/now/v1/cs/voice-interactions

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 7. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    agentId 音声インタラクションをアサインするエージェントの一意の識別子。

    データタイプ：文字列

    デフォルト:仮想エージェントを呼び出す
    callerPhoneNumber 発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。

    データタイプ：文字列

    形式:E.164標準準拠

    デフォルト：なし
    clientSessionId この電話を追跡するために使用される、外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。

    データタイプ：文字列

    デフォルト：なし
    inboundId 音声サービスのアプリケーションプロバイダーの一意の識別子。

    データタイプ：文字列

    デフォルト:チャットから取得
    userId 必須です。音声トランザクションに関連付けられたコールを発信した発信者の電話番号。

    データタイプ：文字列

    形式:音声会話スクリプトを作成したソフトウェアによって定義されます。通常、E.164 標準に準拠しています。

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。JSON の形式が正しくないか、必須パラメーターが渡されませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    interactionId 新しく作成された音声インタラクションレコードのSys_id。
    このsys_idは、次の場合に使用します。

    データタイプ：文字列

    テーブル:インタラクション [interaction]

    cURL 要求

    次のコード例は、音声インタラクションを開始し、コールを特定のエージェントに転送する方法を示しています。

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions" \ 
--request POST \ 
--header "Accept:application/json" \ 
--user 'username':'password' \ 
--header "Content-Type: application/json"\ 
-d '{ 
  "userId": "+14089178877",
  "agentId": "beth.anglin",
  "callerPhoneNumber": "+14089178878",
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z"
}'

    応答：

    {
  "result": {
    "interactionId": "4462cb4753751110b6e8ddeeff7b12ca"
  }
}

    音声インタラクションリソース - POST /cs/voice-interactions/{interactionId}/conversation

    指定されたインタラクションの会話 [sys_cs_conversation] テーブル内に会話レコードを作成します。

    URL 形式

    バージョン管理された URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/conversation

    デフォルト URL: /api/now/v1/cs/voice-interactions/{interactionId}/conversation

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 13. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    interactionId 会話レコードを作成するインタラクションレコードのSys_id。この値は 音声インタラクションリソース - POST /cs/voice-interactions エンドポイントによって返され、インタラクション [interaction] テーブルに格納されます。

    データタイプ：文字列
    表 : 14. クエリパラメーター
    名前 説明
    なし
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    agentId 音声インタラクションをアサインするエージェントの一意の識別子。

    データタイプ：文字列

    デフォルト:仮想エージェントを呼び出す
    callerPhoneNumber 発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。

    データタイプ：文字列

    形式:E.164標準準拠

    デフォルト：なし
    clientSessionId この電話を追跡するために使用される、外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。

    データタイプ：文字列

    デフォルト：なし
    inboundId 音声サービスのアプリケーションプロバイダーの一意の識別子。

    データタイプ：文字列

    デフォルト:チャットからプル
    userId 必須です。音声トランザクションに関連付けられたコールを発信した発信者の電話番号。

    データタイプ：文字列

    形式:音声会話スクリプトを作成したソフトウェアによって定義されます。通常、E.164 標準に準拠しています。

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 16. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 18. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。JSON の形式が正しくないか、必須パラメーターが渡されませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    conversationId 新しく作成された会話レコードのSys_id。

    データタイプ：文字列

    テーブル:会話 [sys_cs_conversation]

    cURL 要求

    次のコード例は、このエンドポイントを呼び出す方法を示しています。

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/7662cb4721751ea0b6e8dda1b27b131f/conversation" \  
--request POST \  
--header "Accept:application/json" \  
--user 'username':'password' \  
--header "Content-Type: application/json"\  
-d '{  
  "userId": "+14089178877", 
  "agentId": "admin@example.com", 
  "callerPhoneNumber": "+14089178878", 
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z" 
}'

    応答：

    { 
  "result": "a47e1afdb7471110b6e8bc15ae11a934" 
}

    音声インタラクションリソース - POST /cs/voice-interactions/{interactionId}/messages

    指定された音声会話メッセージを指定された音声トランザクションレコードに追加します。これらのメッセージは通常、サードパーティベンダーのソフトウェアを使用して生成されます。現在、Amazon Connect のみがサポートされています。

    通話のリアルタイム文字起こし中にこのエンドポイントを複数回呼び出すか、履歴目的で通話を書き写す場合は、すべてのメッセージを 1 回の通話で渡すことができます。リアルタイム会話を処理している場合は、メッセージが適切なタイミングで エージェントワークスペース 表示されるように、このエンドポイントを頻繁に呼び出す必要があります。メッセージは、コールの開始に関連する開始時間と終了時間に基づいて順序付けされます。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/messages

    デフォルト URL: /api/now/v1/cs/voice-interactions/{interactionId}/messages

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 19. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    interactionId 指定されたメッセージを追加するインタラクションレコードのSys_id。この値は 音声インタラクションリソース - POST /cs/voice-interactions エンドポイントによって返され、インタラクション [interaction] テーブルに格納されます。

    データタイプ：文字列
    表 : 20. クエリパラメーター
    名前 説明
    なし
    表 : 21. 要求本文パラメーター (Amazon Connect)
    [Name (名前)] 説明
    <json_string>
    指定された音声インタラクションに添付するメッセージのリスト。
    "<json_string>":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "Number",
    "participantId": "String",
    "sentiment": "String"
  }
]
    <json_string>.attributes
    音声インタラクションに関連付けるキーと値のペア。

    これらは、単純なオブジェクトから複雑な複合オブジェクトまで、あらゆるタイプのデータオブジェクトにすることができます。これらは、Amazon Web Services API を呼び出すときに一意の識別子として使用されます。

    データタイプ：オブジェクトのアレイ

    デフォルト：なし
    <json_string>.beginOffsetMillis 必須です。音声インタラクションの開始から関連するメッセージの開始までの時間オフセット。例:"beginOffsetMillis": 2650。

    データタイプ：長整数

    単位：ミリ秒
    <json_string>.content 必須です。音声インタラクションに追加するメッセージのテキスト。

    データタイプ：文字列
    <json_string>.endOffsetMillis 必須です。音声インタラクションの開始からメッセージの終了までの時間オフセット。例:"endOffsetMillis": 9380。

    データタイプ：長整数

    単位：ミリ秒
    <json_string>.id この音声会話のソース (AmazonConnect など) のメッセージ UUID。ソースメッセージ ID 列の値を設定します。

    データタイプ：文字列

    デフォルト：なし
    <json_string>.isEvent
    Amazon Connect によって設定されますが、現在このメソッドでは使用されていません。関連するメッセージがイベントかどうかを示すフラグ。
    有効な値：
    • true:メッセージはイベントです。
    • false:メッセージはイベントではありません。

    データタイプ：ブーリアン

    デフォルト値：false
    <json_string>.isInternalMessage
    これが内部メッセージであり、発信者に表示しないかどうかを示すフラグ。

    通常、トランスクリプトは内部メッセージと見なされ、エージェントにのみ表示され、発信者には表示されません。さらに、エージェントウィスパーは、サイレントサードパーティが発信者に気付かれずにチャットしたり、電話での会話に持ち込まれたりしてエージェントにアドバイスを提供する場合に使用されます。問い合わせユーザーにはこれらのメッセージは聞こえませんが、エージェントには表示されます。

    有効な値：
    • true:内部メッセージ。発信者には表示されません。
    • false:内部メッセージではありません。発信者に表示されます。

    データタイプ：ブーリアン

    デフォルト値：false
    <json_string>.loudnessScore
    通話中の顧客またはエージェントの発言の声に関する測定値。

    Contact Lens には、相手がどこで大声で話しているか、否定的な感情を持っている可能性があるかを示す会話の分析が表示されます。

    データタイプ：数値

    範囲:-1.0 (負) 〜 1.0 (正)

    デフォルト：Null
    <json_string>.participantId
    必須。メッセージに関連付けられた参加者。
    有効な値：
    • エージェント
    • 顧客

    データタイプ：文字列
    <json_string>.sentiment
    メッセージの感情。

    この値は、サードパーティプロバイダーによって生成されます。ServiceNowインスタンス構成設定に基づいて、この値は正、負、または中立のいずれかに変換され、会話およびインタラクションレコードに保存されます。

    有効な値：
    • －
    • ニュートラル
    • ＋

    データタイプ：文字列

    デフォルト：Null

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 22. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 23. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 24. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。JSON の形式が正しくないか、必須パラメーターが渡されませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 コールの結果を説明するメッセージ。

    データタイプ：文字列
    会話 ID 作成された音声インタラクションメッセージレコードのSys_id。

    データタイプ：文字列

    テーブル:音声トランスクリプト会話メッセージ [sys_cs_message_voice_transcript]

    cURL 要求

    次の例は、既存の音声インタラクションレコードにメッセージを追加する方法を示しています。

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/messages" \ 
--request POST \
--header "Accept:application/json" \
--header "Content-Type: application/json"\ 
--user 'username':'password' \
-d ' [ 
  { 
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 10000,  
    "content": "This is John. How can I help you?",  
    "endOffsetMillis": 15000,  
    "id": "954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8",  
    "participantId": "AGENT",  
    "sentiment": "NEUTRAL",  
    "loudnessScore": "null",  
    "attributes": [{  
      "key": "key1",  
      "value": "value1"  
      }, {  
      "key": "key2",  
      "value": "value2"  
    }] 
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 20000,  
    "content": "Uh, yes, John. Um, I'm a little very frustrated right now.",  
    "endOffsetMillis": 25000,  
    "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",  
    "participantId": "CUSTOMER",  
    "sentiment": "NEGATIVE"  
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 30000,  
    "content": "I am sorry to hear that",  
    "endOffsetMillis": 35000,  
    "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",  
    "participantId": "AGENT",  
    "sentiment": "NEGATIVE",  
 
  },  
  {  
    "isEvent":"false",
    "isInternalMessage":"false",
    "beginOffsetMillis":40000,
    "content":"Can you help me with my insurance? My ssn is 123-12-1234",
    "endOffsetMillis":45000,
    "id":"ab09b3b6-23fd-4e41-be05-6b2b53c19059",
    "participantId":"CUSTOMER",
    "sentiment":"NEUTRAL" 
  },  
  {  
    "isEvent":"False",
    "isInternalMessage":"False",
    "beginOffsetMillis":50000, 
    "content":"Of course, let me check your account",
    "endOffsetMillis":55000,
    "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",
    "participantId":"AGENT",
    "sentiment":"NEUTRAL" 
  }  
]'

    応答：

    { 
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2" 
}

    音声インタラクションリソース - POST /cs/voice-interactions/transcript

    コールの完了後に、既存の音声インタラクションにメッセージを追加します。この API を使用して、エージェントと発信者間の音声通話の文字起こしメッセージを添付できます。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/transcript

    デフォルト URL: /api/now/v1/cs/voice-interactions/{interactionId}/transcript

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

    サポートされている要求パラメーター

    表 : 25. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 26. クエリパラメーター
    名前 説明
    なし
    表 : 27. 要求本文パラメーター (XML または JSON)
    名前 説明
    会話開始 会話の開始時間

    データタイプ：文字列

    形式：YYYY-MM-DD HH:MM:SS

    テーブル:インタラクション [interaction]
    interactionId 指定されたメッセージを追加するインタラクションレコードのSys_id。この値は 音声インタラクションリソース - POST /cs/voice-interactions エンドポイントによって返されます。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    ソース 会話のトランスクリプトを最初に作成したチャネルの名前。

    現在サポートされている値は Amazon Connect のみです。

    データタイプ：文字列
    写し 指定された音声インタラクションに添付するメッセージのリスト。
    "transcript":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "String",
    "participantId": "String",
    "sentiment": "String"
  }
]

    データタイプ：オブジェクトのアレイ
    transcript.attributes
    音声インタラクションに関連付けるキーと値のペア。

    これらは、単純なオブジェクトから複雑な複合オブジェクトまで、あらゆるタイプのデータオブジェクトにすることができます。これらは、Amazon Web Services API を呼び出すときに一意の識別子として使用されます。

    データタイプ：オブジェクトのアレイ

    デフォルト：なし
    transcript.beginOffsetMillis 必須です。音声インタラクションの開始から関連するメッセージの開始までの時間オフセット。例:"beginOffsetMillis": 2650。

    データタイプ：長整数

    単位：ミリ秒
    transcript.content 必須です。音声インタラクションに追加するメッセージのテキスト。

    データタイプ：文字列
    transcript.endOffsetMillis 必須です。音声インタラクションの開始からメッセージの終了までの時間オフセット。例:"endOffsetMillis": 9380。

    データタイプ：長整数

    単位：ミリ秒
    transcript.id この音声会話のソース (AmazonConnect など) のメッセージ UUID。ソースメッセージ ID 列の値を設定します。

    データタイプ：文字列

    デフォルト：なし
    transcript.isEvent
    Amazon Connect によって設定されますが、現在このメソッドでは使用されていません。関連するメッセージがイベントかどうかを示すフラグ。
    有効な値：
    • true:メッセージはイベントです。
    • false:メッセージはイベントではありません。

    データタイプ：ブーリアン

    デフォルト値：false
    transcript.isInternalMessage
    これが内部メッセージであり、発信者に表示しないかどうかを示すフラグ。

    通常、トランスクリプトは内部メッセージと見なされ、エージェントにのみ表示され、発信者には表示されません。さらに、エージェントウィスパーは、サイレントサードパーティが発信者に気付かれずにチャットしたり、電話での会話に持ち込まれたりしてエージェントにアドバイスを提供する場合に使用されます。問い合わせユーザーにはこれらのメッセージは聞こえませんが、エージェントには表示されます。

    有効な値：
    • true:内部メッセージ。発信者には表示されません。
    • false:内部メッセージではありません。発信者に表示されます。

    データタイプ：ブーリアン

    デフォルト値：false
    transcript.loudnessScore
    通話中の顧客またはエージェントの発言の声に関する測定値。

    Contact Lens には、相手がどこで大声で話しているか、否定的な感情を持っている可能性があるかを示す会話の分析が表示されます。

    データタイプ：数値

    範囲:-1.0 (負) 〜 1.0 (正)

    デフォルト：Null
    transcript.participantId
    必須。メッセージに関連付けられた参加者。
    有効な値：
    • エージェント
    • 顧客

    データタイプ：文字列
    transcript.sentiment
    メッセージの感情。

    この値は、サードパーティプロバイダーによって生成されます。ServiceNowインスタンス構成設定に基づいて、この値は正、負、または中立のいずれかに変換され、会話およびインタラクションレコードに保存されます。

    有効な値：
    • －
    • ニュートラル
    • ＋

    データタイプ：文字列

    デフォルト：Null

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 28. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 29. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 30. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。JSON の形式が正しくないか、必須パラメーターが渡されませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    結果 コールの結果を説明するメッセージ。

    データタイプ：文字列
    会話 ID メッセージが添付された音声会話テーブルのSys_id。

    データタイプ：文字列

    テーブル:会話 [sys_cs_message_conversation]

    cURL 要求

    次の例は、既存の音声インタラクションレコードにメッセージを追加する方法を示しています。

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/transcript" \  
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type: application/json"\  
--user 'username':'password' \ 
-d ' { 
  "interactionId": "e67a6c30c7233010967a34c91dc26068", 
  "source": "Amazon Connect", 
  "conversationStarted": "2021-08-06 15:07:51", 
  "transcript": [ 
    { 
      "isEvent": "False", 
      "isInternalMessage": "False", 
      "beginOffsetMillis": 100000, 
      "content": "This is John. How can I help you?", 
      "endOffsetMillis": 150000, 
      "id": "954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8", 
      "participantId": "AGENT", 
      "sentiment": "NEUTRAL" 
    }, 
    { 
      "isEvent": "False",
      "isInternalMessage": "False", 
      "beginOffsetMillis": 200000, 
      "content": "Uh, yes, John. Um, I'm a little frustrated right now.", 
      "endOffsetMillis": 25000, 
      "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f", 
      "participantId": "CUSTOMER", 
      "sentiment": "NEGATIVE" 
    } 
  ] 
} ' 

    応答：

    {  
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2"  
}