VoiceTranscriptObject - スコープ指定

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：24分

    • VoiceTranscriptObject スクリプト可能 API は、サードパーティの音声会話トランスクリプトデータを ServiceNow インスタンス内のテーブルに保存するメソッドを提供します。

    VoiceTranscriptObject クラスを呼び出すときは、sn_cs 名前空間識別子を使用します。

    顧客の詳細と会話が表示されたエージェントワークスペースページ。

    可用性

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

    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>.attributes オブジェクトのアレイ
    音声インタラクションに関連付けるキーと値のペア。

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

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

    単位：ミリ秒
    <json_string>.content 文字列 必須です。音声インタラクションに追加するメッセージのテキスト。
    <json_string>.endOffsetMillis Long 必須です。音声インタラクションの開始とメッセージの終了の間の時間オフセット。例:"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_transcript] テーブルにデータを保存します。CSM はこれらのテーブルの情報にアクセスして、音声会話のトランスクリプトを表示します。

    表 : 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": [] 
    } 
  ] 
}
    表 : 8. 返される内容
    タイプ 説明
    文字列 メソッド呼び出しの結果。
    考えられる結果:
    • 音声会話のトランスクリプトが正常に保存されました。会話 ID: <transcript_record_sys_id>
    • 音声会話のトランスクリプトを保存できませんでした。詳細エラー: <エラーの詳細>
    • エラー:要求に InteractionId がありません。
    • エラー:要求で指定されたインタラクションは既に処理されています。

    この例では、 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] テーブル内に音声インタラクションレコードを作成します。

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

    表 : 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"}