VoiceTranscriptObject - Scoped

The VoiceTranscriptObject scriptable API provides methods to save third-party voice conversation transcript data to a table within a ServiceNow instance.

When calling the VoiceTranscriptObject class, use the sn_cs namespace identifier.

Availability

This API is available in the base ServiceNow system. Access is restricted by the ACLs imposed on the Interaction [interaction] and Conversation [sys_cs_conversation] tables.

Parent Topic:Server API reference

VoiceTranscriptObject - addVoiceInteractionMessage(String interactionId, String Json)

Adds the specified messages to the specified voice transaction record.

You can call this endpoint multiple times during real-time transcribing of the call or pass all messages in a single call if you are transcribing the call for historical purposes. If you are processing a real-time conversation, you should call this endpoint frequently, so that the messages appear in Agent Workspace in a timely manner. Messages are ordered based on their start and end times in relation to the start of the call.

"<json_string>":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "Number",
    "participantId": "String",
    "sentiment": "String"
  }
]

The following example shows how to add messages to an existing voice interaction record.

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))); 

Output:

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

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

VoiceTranscriptObject - createConversation(String interactionId, String Json)

Creates a conversation record within the Conversation [sys_cs_conversation] table for the specified interaction.

"<json_string>": {
  "agentId": "String",
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userId": "String"

The following code example shows how to create a new conversation record using this method.

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

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

Output:

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

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

VoiceTranscriptObject - endVoiceInteraction(String interactionId, String Json)

Terminates the specified voice interaction. Once called, no additional voice messages are translated and stored for the phone conversation.

"<json_string>": {
  "recordingURL": "String"
}

The following code example shows how to end an active voice interaction and pass in the original voice recording URL.

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

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

Output:

// Success
Success

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

VoiceTranscriptObject - saveVoiceConversationTranscript(String voiceConversationJson)

Saves third-party voice conversation transcript data to tables within a ServiceNow instance that is then accessible through Customer Service Management (CSM).

These voice conversations are typically generated using third-party vendor software. This method parses the passed JSON and saves the data into the Conversation [sys_cs_conversation], Conversation Message [sys_cs_message], and Voice Transcript Conversation Message [sys_cs_message_voice_transcript] tables within the ServiceNow instance. CSM accesses the information in these tables to display the voice conversation transcripts.

</td></tr></tbody>
</table>

<table id="table_ucz_mly_prb" class="returns"><thead><tr><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

String

</td><td>

Results of the method call.Possible return results:

-   Voice conversation transcript has been successfully saved. Conversation id: `<transcript_record_sys_id>`
-   Voice conversation transcript could not be saved. Detail error: `<error details>`
-   ERROR: InteractionId is missing in the request.
-   ERROR: Interaction specified in the request has already been processed.

</td></tr></tbody>
</table>

This example shows how to call the saveVoiceConversationTranscript\(\) method to save an Amazon Connect transcript.

Output:

## VoiceTranscriptObject - startVoiceInteraction\(String Json\)

Creates a voice interaction record within the Interaction \[interaction\] table.

You must create this record before trying to save any transcribed voice messages. You can also use this method to assign a call to a specific agent by passing in their specific user ID.

<table id="table_lkt_hkl_x5b" class="parameters"><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

&lt;json\_string&gt;

</td><td>

String

</td><td id="vto-json_string-start-entry">

JSON string of the input parameters.

</td></tr><tr><td>

&lt;json\_string&gt;.agentId

</td><td>

String

</td><td id="vto-json_string-agentId-entry">

Unique identifier of the agent to assign the voice interaction to. Default: None. Assigned to the next available agent.

Table: In the User ID field of the User \[sys\_user\] table.

</td></tr><tr><td>

&lt;json\_string&gt;.callerPhoneNumber

</td><td>

String

</td><td id="vto-json_string-callerPhoneNumber-entry">

Caller's callback phone number. This is the number the agent uses to reach the caller in case the call drops. Format: E.164 standard compliant

Default: None

</td></tr><tr><td>

&lt;json\_string&gt;.clientSessionId

</td><td>

String

</td><td id="vto-json_string-clientSessionId-entry">

Unique identifier of a record in an external system used to track this phone call. This information links the records between the two systems. Default: None

</td></tr><tr><td>

&lt;json\_string&gt;.inboundId

</td><td>

String

</td><td id="vto-json_string-inboundId-entry">

Unique identifier of the application provider for the voice service. Default: Pull from chat

Table: In the Inbound ID field of the Provider Channel Application \[sys\_cs\_provider\_application\] table.

</td></tr><tr><td>

&lt;json\_string&gt;.userId

</td><td>

String

</td><td id="vto-json_string-userId-entry">

Required. Phone number of the caller who made the call associated with the voice transaction.Format: Defined by the software that created the voice conversation script. Typically E.164 standard compliant.

</td></tr></tbody>
</table>

<table id="table_mkt_hkl_x5b" class="returns"><thead><tr><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

String

</td><td>

Results of the method call.Possible return results:

-   Success: \{"interactionId":"&lt;interaction\_sys\_id&gt;","status":"SUCCESS"\}
-   Error: \{"error":"&lt;error message&gt;","status":"FAILED"\}

</td></tr></tbody>
</table>

The following code example shows how to create a voice interaction record.

Output: