VoiceTranscriptObject - スコープ指定

VoiceTranscriptObject - addVoiceInteractionMessage(文字列 interactionId, 文字列 json)

指定された音声トランザクションレコードに指定されたメッセージを追加します。

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

表 : 1. パラメーター
名前	タイプ	説明
interactionId	文字列	指定されたメッセージを追加するインタラクションレコードのSys_id。この値は VoiceTranscriptObject - startVoiceInteraction(文字列 json) メソッドによって返され、インタラクション [interaction] テーブルに格納されます。
<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>.属性	オブジェクトのアレイ	音声インタラクションに関連付けるキーと値のペア。これらは、単純なオブジェクトから複雑な複合オブジェクトまで、あらゆるタイプのデータオブジェクトにすることができます。これらは、Amazon Web サービス API を呼び出すときに一意の識別子として使用されます。デフォルト：なし
<json_string>.beginOffsetMillis	長	必須です。音声インタラクションの開始と関連するメッセージの開始の間の時間オフセット。例:"beginOffsetMillis": 2650。単位：ミリ秒
<json_string>.コンテンツ	文字列	必須です。音声インタラクションに追加するメッセージのテキスト。
<json_string>.endOffsetMillis	長	必須です。音声インタラクションの開始からメッセージの終了までの時間オフセット。例:"endOffsetMillis": 9380。単位：ミリ秒
<json_string>.id	文字列	この音声会話のソースのメッセージ UUID (AmazonConnect など)。ソースメッセージ ID 列の値を設定します。デフォルト：なし
<json_string>.isEvent	ブール	Amazon Connect によって設定されますが、メソッドでは現在使用されていません。関連付けられたメッセージがイベントかどうかを示すフラグ。有効な値： true:メッセージはイベントです。 false:メッセージはイベントではありません。デフォルト値：false
<json_string>.isInternalMessage	ブール	これが内部メッセージであり、発信者に表示してはならないかどうかを示すフラグ。文字起こしは通常、内部メッセージと見なされ、エージェントにのみ表示され、発信者には表示されません。さらに、エージェントウィスパーは、サイレントなサードパーティがチャット中、または発信者に知られずに電話での会話に持ち込まれ、エージェントにアドバイスを提供する場合に使用されます。発信者はこれらのメッセージを聞いたり見たりしませんが、エージェントには聞こえます。有効な値： true:内部メッセージ。発信者に表示されません。 false:内部メッセージではなく、発信者に表示します。デフォルト値：false
<json_string>.loudnessScore	番号	顧客またはエージェントが通話中にどれだけ大きな声で話しているかに関する測定。 Contact Lens は、会話の分析を表示し、どこで大声で話していて、否定的な感情を持っているかを示します。デフォルト：Null
<json_string>.participantId	文字列	必須。メッセージに関連付けられた参加者。有効な値：顧客エージェント
<json_string>.sentiment	文字列	メッセージの感情。この値は、サードパーティプロバイダーによって生成されます。ServiceNowインスタンス構成設定に基づいて、この値は正、負、または中立のいずれかに変換され、会話およびインタラクションレコードに保存されます。有効な値：－ニュートラル＋デフォルト：Null

表 : 2. 返される内容
タイプ	説明
文字列	コールの結果を説明するメッセージ。
文字列	成功した場合、作成された音声インタラクションメッセージレコードのsys_id。音声トランスクリプト会話メッセージ [sys_cs_message_voice_transcript] テーブルにあります。エラーが発生した場合は、失敗の理由を説明するエラーメッセージ。

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

var request = [ 
  { 
    "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 very frustrated right now.",
    "endOffsetMillis":25000,
    "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",
    "participantId":"CUSTOMER",
    "sentiment":"NEGATIVE" 
  } 
]; 

gs.log(sn_cs.VoiceTranscriptObject.addVoiceInteractionMessage("1f4ed6fdb7471110b6e8bc15ae11a971", JSON.stringify(request)));

出力:

// Success
Voice conversation transcript has been successfully saved. Conversation id: ea01113cb7f71110b6e8bc15ae11a94d

// Error
Exception occurred while adding the message: <error message>

VoiceTranscriptObject - createConversation(文字列 interactionId, 文字列 json)

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

表 : 3. パラメーター
名前	タイプ	説明
interactionId	文字列	会話レコードを作成するインタラクションレコードのSys_id。この値は VoiceTranscriptObject - startVoiceInteraction(文字列 json) メソッドによって返され、インタラクション [interaction] テーブルに格納されます。
<json_string>	文字列	入力パラメーターの JSON 文字列。 `"<json_string>": { "agentId": "String", "callerPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userId": "String"`
<json_string>.agentId	文字列	音声インタラクションをアサインするエージェントの一意の識別子。ユーザー [sys_user] テーブルの [ユーザー ID] フィールドにあります。デフォルト：なし。次に対応可能なエージェントにアサインされます。
<json_string>.callerPhoneNumber	文字列	発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。フォーマット:E.164規格準拠デフォルト：なし
<json_string>.clientSessionId	文字列	この電話を追跡するために使用される外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。デフォルト：なし
<json_string>.inboundId	文字列	音声サービスのアプリケーションプロバイダーの一意の識別子。プロバイダーチャネルアプリケーション [sys_cs_provider_application] テーブルの [受信 ID] フィールドにあります。デフォルト:チャットからプル
<json_string>.userId	文字列	必須です。音声トランザクションに関連付けられたコールを発信した発信者の電話番号。形式:音声会話スクリプトを作成したソフトウェアによって定義されます。通常、E.164 標準に準拠しています。

表 : 4. 返される内容
タイプ	説明
文字列	成功した場合、新しく作成された会話レコードのsys_idを返します。会話 [sys_cs_conversation] テーブルにあります。エラーが発生した場合は、詳細なエラーメッセージを返します。

次のコード例は、このメソッドを使用して新しい会話レコードを作成する方法を示しています。

var request = { 
  "userId": "+14089178877"
}; 

var response = sn_cs.VoiceTranscriptObject.createConversation("e0fc03d7b7a21110b6e8bc15ae11a96c", JSON.stringify(request)); 
gs.log("Conversation id: " + JSON.stringify(response));

出力:

// Success
{"conversationId":"28435dbcb7f71110b6e8bc15ae11a972","status":"SUCCESS"}

// Error
{"error":"Exception occurred while creating a conversation: <error message>","status":"FAILED"}

VoiceTranscriptObject - endVoiceInteraction(文字列 interactionId, 文字列 json)

指定された音声インタラクションを終了します。いったんコールされると、電話での会話用にそれ以上の音声メッセージが翻訳されて保存されることはありません。

表 : 5. パラメーター
名前	タイプ	説明
interactionId	文字列	音声インタラクションを終了するインタラクションレコードのSys_id。インタラクション [interaction] テーブルにあります。
<json_string>	JSON 文字列	オプション。音声インタラクションに関する追加情報を含むパラメーター。 `"<json_string>": { "recordingURL": "String" }`
<json_string>.recordingURL	文字列	オプション。元の音声録音がある URL。設定されている場合、この URL はエージェントワークスペースで表示されます。デフォルト：なし

表 : 6. 返される内容
タイプ	説明
文字列	成功した場合は `[成功`] を返します。エラーが発生した場合は、詳細なエラーメッセージを返します。

次のコード例は、アクティブな音声操作を終了し、元の音声録音 URL を渡す方法を示しています。

var request = { 
  "recordingURL": "https://servicenow.zoom.us/rec/QbF7XmPFHPlX1LG" 
}; 

gs.log(sn_cs.VoiceTranscriptObject.endVoiceInteraction("1f4ed6fdb7471110b6e8bc15ae11a971", JSON.stringify(request)));

出力:

// Success
Success

// Error
Exception occurred while ending the interaction: <error message>

VoiceTranscriptObject - saveVoiceConversationTranscript(文字列 voiceConversationJson)

サードパーティの音声会話のトランスクリプトデータを ServiceNow インスタンス内のテーブルに保存し、カスタマーサービス管理 (CSM)を介してアクセスできるようにします。

通常、こういった音声会話はサードパーティベンダーのソフトウェアを使用して生成されます。このメソッドでは、渡された JSON を解析し、ServiceNow インスタンス内の会話 [sys_cs_conversation]、会話メッセージ [sys_cs_message]、および音声トランスクリプト会話メッセージ [sys_cs_message_voice_transscript] テーブルにデータを保存します。CSM はこれらのテーブルの情報にアクセスして、音声会話のトランスクリプトを表示します。

名前タイプ説明

voiceConversationJson

文字列

表 : 7. パラメーター
名前	タイプ	説明
voiceConversationJson	文字列	保存する音声会話を表す JSON。この JSON は、OpenFrame などの別の ServiceNow プラグインによって送信されます。Amazon などのサードパーティベンダーがその JSON をプラグインに送信します。関連するプラグインが音声会話を解析し、必要な形式で仮想エージェントに JSON を送信します。たとえば、以下は Amazon Connect の会話の例です。 { "interactionId":"bgr09b5a-7308-47b2-jy97-737de9f45d19", "source":"AmazonConnect", "conversationStarted":"2021-08-06 15:07:51", "transcript":[ { "isEvent":"False", "isInternalMessage":"False", "beginOffsetMillis":2650, "content":"This is John. How can I help you? Yeah,", "endOffsetMillis":9380, "id":"954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8", "participantId":"AGENT", "Sentiment":"NEUTRAL", "loudnessScore":"null,null", "attributes": [{ "key":"key1", "value":"value1" },{ "key":"key2", "value":"value2" }] }, { "isEvent":"False", "isInternalMessage":"False", "beginOffsetMillis":9120, "content":"Uh, yes, John. I'm a little very frustrated right now.", "endOffsetMillis":22900, "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f", "participantId":"CUSTOMER", "sentiment":"NEGATIVE", "loudnessScore":"null,null", "attributes": [{ "key":"key1", "value":"value1" },{ "key":"key2", "value":"value2" } ] }, { "isEvent":"True", "isInternalMessage":"True", "beginOffsetMillis":23590, "content":"Agent asked for help in chat", "endOffsetMillis":30610, "id":"ab09b3b6-23fd-4e41-be05-6b2b53c19059", "participantId":"CUSTOMER", "sentiment":"NEUTRAL", "loudnessScore":"null,null,null,null", "attributes": [] } ] }

保存する音声会話を表す JSON。この JSON は、OpenFrame などの別の ServiceNow プラグインによって送信されます。Amazon などのサードパーティベンダーがその JSON をプラグインに送信します。関連するプラグインが音声会話を解析し、必要な形式で仮想エージェントに JSON を送信します。

たとえば、以下は Amazon Connect の会話の例です。

{ 
  "interactionId":"bgr09b5a-7308-47b2-jy97-737de9f45d19", 
  "source":"AmazonConnect", 
  "conversationStarted":"2021-08-06 15:07:51", 
  "transcript":[ 
    { 
      "isEvent":"False", 
      "isInternalMessage":"False", 
      "beginOffsetMillis":2650, 
      "content":"This is John. How can I help you? Yeah,", 
      "endOffsetMillis":9380, 
      "id":"954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8", 
      "participantId":"AGENT", 
      "Sentiment":"NEUTRAL", 
      "loudnessScore":"null,null", 
      "attributes": [{ 
        "key":"key1", 
        "value":"value1" 
      },{ 
        "key":"key2", 
        "value":"value2" 
      }] 
    }, 
    { 
      "isEvent":"False", 
      "isInternalMessage":"False", 
      "beginOffsetMillis":9120, 
      "content":"Uh, yes, John. I'm a little very frustrated right now.", 
      "endOffsetMillis":22900, 
      "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f", 
      "participantId":"CUSTOMER", 
      "sentiment":"NEGATIVE", 
      "loudnessScore":"null,null", 
      "attributes": [{ 
        "key":"key1", 
        "value":"value1" 
      },{ 
        "key":"key2", 
        "value":"value2" 
      } ] 
    }, 
    { 
      "isEvent":"True", 
      "isInternalMessage":"True", 
      "beginOffsetMillis":23590, 
      "content":"Agent asked for help in chat", 
      "endOffsetMillis":30610, 
      "id":"ab09b3b6-23fd-4e41-be05-6b2b53c19059", 
      "participantId":"CUSTOMER", 
      "sentiment":"NEUTRAL", 
      "loudnessScore":"null,null,null,null", 
      "attributes": [] 
    } 
  ] 
}

表 : 8. 返される内容
タイプ	説明
文字列	メソッド呼び出しの結果。返される可能性のある結果は次のとおりです。音声会話のトランスクリプトが正常に保存されました。会話 ID：`<transcript_record_sys_id>` 音声会話のトランスクリプトを保存できませんでした。(Voice conversation transcript could not be saved.) 詳細エラー：`<エラーの詳細>` (Detail error: <error details>) エラー：要求に InteractionId がありません。(ERROR: InteractionId is missing in the request.) エラー：要求で指定されたインタラクションはすでに処理されています。 (ERROR: Interaction specified in the request has already been processed.)

この例では、 saveVoiceConversationTranscript() メソッドを呼び出して Amazon Connect トランスクリプトを保存する方法を示します。

var voiceConversationJson = "{\n" +
  "   \"interactionId\":\"e67a6c30c7233010967a34c91dc26068\",\n" +
  "   \"source\":\"AmazonConnect\",\n" +
  "   \"conversationStarted\":\"2021-08-06 15:07:51\",\n" +
  "   \"transcript\":[\n" +
  "      {\n" +
  "         \"isEvent\":\"False\",\n" +
  "         \"isInternalMessage\":\"False\",\n" +
  "         \"beginOffsetMillis\":2650,\n" +
  "         \"content\":\"This is John. How can I help you? Yeah,\",\n" +
  "         \"endOffsetMillis\":9380,\n" +
  "         \"id\":\"954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8\",\n" +
  "         \"participantId\":\"AGENT\",\n" +
  "         \"sentiment\":\"NEUTRAL\",\n" +
  "         \"loudnessScore\":\"null,null\",\n" +
  "         \"attributes\": [{\n" +
  "           \"key\":\"key1\",\n" +
  "           \"value\":\"value1\"\n" +
  "         },{\n" +
  "           \"key\":\"key2\",\n" +
  "           \"value\":\"value2\"\n" +
  "         }\n" +
  " ]\n" +
  "      },\n" +
  "      {\n" +
  "         \"isEvent\":\"False\",\n" +
  "         \"isInternalMessage\":\"False\",\n" +
  "         \"beginOffsetMillis\":9120,\n" +
  "         \"content\":\"Uh, yes, John. I'm a little frustrated right now.\",\n" +
  "         \"endOffsetMillis\":22900,\n" +
  "         \"id\":\"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f\",\n" +
  "         \"participantId\":\"CUSTOMER\",\n" +
  "         \"sentiment\":\"NEGATIVE\",\n" +
  "         \"loudnessScore\":\"null,null\",\n" +
  "         \"attributes\": [{\n" +
  "           \"key\":\"key1\",\n" +
  "           \"value\":\"value1\"\n" +
  "         },{\n" +
  "           \"key\":\"key2\",\n" +
  "           \"value\":\"value2\"\n" +
  "         }\n" +
  " ]\n" +
  "      },\n" +
  "      {\n" +
  "         \"isEvent\":\"False\",\n" +
  "         \"isInternalMessage\":\"False\",\n" +
  "         \"beginOffsetMillis\":9120,\n" +
  "         \"content\":\"I am sorry to hear that\",\n" +
  "         \"endOffsetMillis\":22900,\n" +
  "         \"id\":\"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f\",\n" +
  "         \"participantId\":\"AGENT\",\n" +
  "         \"sentiment\":\"NEGATIVE\",\n" +
  "         \"loudnessScore\":\"null,null\",\n" +
  "         \"attributes\": [{\n" +
  "           \"key\":\"key1\",\n" +
  "           \"value\":\"value1\"\n" +
  "         },{\n" +
  "           \"key\":\"key2\",\n" +
  "           \"value\":\"value2\"\n" +
  "         }\n" +
  " ]\n" +
  "      },\n" +
  "      {\n" +
  "         \"isEvent\":\"false\",\n" +
  "         \"isInternalMessage\":\"false\",\n" +
  "         \"beginOffsetMillis\":23590,\n" +
  "         \"content\":\"I am having problems with my computer\",\n" +
  "         \"endOffsetMillis\":30610,\n" +
  "         \"id\":\"ab09b3b6-23fd-4e41-be05-6b2b53c19059\",\n" +
  "         \"participantId\":\"CUSTOMER\",\n" +
  "         \"sentiment\":\"NEUTRAL\",\n" +
  "  \"loudnessScore\":\"null,null,null,null\",\n" +
  "         \"attributes\": [\n" +
  "  ]\n" +
  "      },\n" +
  "      {\n" +
  "         \"isEvent\":\"True\",\n" +
  "         \"isInternalMessage\":\"True\",\n" +
  "         \"beginOffsetMillis\":23590,\n" +
  "         \"content\":\"Agent asked for help in chat\",\n" +
  "         \"endOffsetMillis\":30610,\n" +
  "         \"id\":\"ab09b3b6-23fd-4e41-be05-6b2b53c19059\",\n" +
  "         \"participantId\":\"CUSTOMER\",\n" +
  "         \"sentiment\":\"NEUTRAL\",\n" +
  "  \"loudnessScore\":\"null,null,null,null\",\n" +
  "         \"attributes\": [\n" +
  "  ]\n" +
  "      }\n" +
  "   ]\n" +
  "}\n";
var result = sn_cs.VoiceTranscriptObject.saveVoiceConversationTranscript(voiceConversationJson);
gs.log(result);

出力:

Voice conversation transcript has been successfully saved. Conversation id: 9c573169c611228700193229fff72400

VoiceTranscriptObject - startVoiceInteraction(文字列 json)

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

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

表 : 9. パラメーター
名前	タイプ	説明
<json_string>	文字列	入力パラメーターの JSON 文字列。 `"<json_string>": { "agentId": "String", "callerPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userId": "String"`
<json_string>.agentId	文字列	音声インタラクションをアサインするエージェントの一意の識別子。ユーザー [sys_user] テーブルの [ユーザー ID] フィールドにあります。デフォルト：なし。次に対応可能なエージェントにアサインされます。
<json_string>.callerPhoneNumber	文字列	発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。フォーマット:E.164規格準拠デフォルト：なし
<json_string>.clientSessionId	文字列	この電話を追跡するために使用される外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。デフォルト：なし
<json_string>.inboundId	文字列	音声サービスのアプリケーションプロバイダーの一意の識別子。プロバイダーチャネルアプリケーション [sys_cs_provider_application] テーブルの [受信 ID] フィールドにあります。デフォルト:チャットからプル
<json_string>.userId	文字列	必須です。音声トランザクションに関連付けられたコールを発信した発信者の電話番号。形式:音声会話スクリプトを作成したソフトウェアによって定義されます。通常、E.164 標準に準拠しています。

表 : 10. 返される内容
タイプ	説明
文字列	メソッド呼び出しの結果。返される可能性のある結果は次のとおりです。成功: {"interactionId":"<interaction_sys_id>","status":"SUCCESS"} エラー: {"error":"<error message>","status":"FAILED"}

次のコード例は、音声インタラクションレコードを作成する方法を示しています。

var request = { 
  "userId": "+14089178877", 
  "callerPhoneNumber": "+14089178878", 
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z" 
}; 
var response = sn_cs.VoiceTranscriptObject.startVoiceInteraction(JSON.stringify(request)); 
gs.log(JSON.stringify(response));

出力:

// Success 
{"interactionId":"ea01113cb7f71110b6e8bc15ae11a950","status":"SUCCESS"}

// Error
{"error":"Exception occurred while starting the interaction: <error message>","status":"FAILED"}

VoiceTranscriptObject - スコープ指定

Xanadu API リファレンス

VoiceTranscriptObject - スコープ指定

可用性

VoiceTranscriptObject - addVoiceInteractionMessage(文字列 interactionId, 文字列 json)

VoiceTranscriptObject - createConversation(文字列 interactionId, 文字列 json)

VoiceTranscriptObject - endVoiceInteraction(文字列 interactionId, 文字列 json)

VoiceTranscriptObject - saveVoiceConversationTranscript(文字列 voiceConversationJson)

VoiceTranscriptObject - startVoiceInteraction(文字列 json)