VoiceTranscriptObject : inclus dans le champ d’application

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 10 minutes de lecture

    • L’API scriptable VoiceTranscriptObject fournit des méthodes pour enregistrer les données de transcription de conversation vocale tierces dans une table au sein d’une ServiceNow instance.

    Lorsque vous appelez la classe VoiceTranscriptObject , utilisez l’identificateur d’espace de noms sn_cs .

    Disponibilité

    Cette API est disponible dans le système de base ServiceNow . L’accès est restreint par les ACL imposées aux tables Interaction [interaction] et Conversation [sys_cs_conversation].

    VoiceTranscriptObject : addVoiceInteractionMessage(String interactionId, String Json)

    Ajoute les messages spécifiés à l’enregistrement de transaction vocale spécifié.

    Vous pouvez appeler ce point de terminaison plusieurs fois pendant la transcription en temps réel de l’appel ou transmettre tous les messages en un seul appel si vous transcrivez l’appel à des fins historiques. Si vous traitez une conversation en temps réel, vous devez appeler ce point de terminaison fréquemment, afin que les messages s’affichent Espace de travail d'agent en temps opportun. Les messages sont classés en fonction de leurs heures de début et de fin par rapport au début de l’appel.

    Tableau 1. Paramètres
    Nom Type Description
    interactionId Chaîne Sys_id de l’enregistrement d’interaction auquel ajouter les messages spécifiés. Cette valeur est renvoyée par la VoiceTranscriptObject : startVoiceInteraction(String JSON) méthode.

    Table : Interaction [interaction]
    <json_string> Chaîne (tableau d’objets)
    Liste des messages à joindre à l’interaction vocale spécifiée.
    "<json_string>":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "Number",
    "participantId": "String",
    "sentiment": "String"
  }
]
    <json_string>.attributs Tableau d'objets
    Paires clé-valeur à associer à l’interaction vocale.

    Il peut s’agir de n’importe quel type d’objet de données, des objets simples aux objets composés complexes. Ils sont utilisés comme identificateurs uniques lors de l’appel des API Amazon Web Services.

    Par défaut : aucun
    <json_string>.beginOffsetMillis Long Obligatoire. Décalage temporel entre le début de l’interaction vocale et le début du message associé. Par exemple : « beginOffsetMillis » : 2650.

    Unité : millisecondes
    <json_string>.content Chaîne Obligatoire. Texte du message à ajouter à l’interaction vocale.
    <json_string>.endOffsetMillis Long Obligatoire. Décalage temporel entre le début de l’interaction vocale et la fin du message. Par exemple : « endOffsetMillis » : 9380.

    Unité : millisecondes
    <json_string>.id Chaîne UUID de message de la source de cette conversation vocale, par exemple pour AmazonConnect. Définit la valeur de colonne d’ID du message source.

    Par défaut : aucun
    <json_string>.isEvent Booléen
    Défini par Amazon Connect mais non actuellement utilisé par la méthode. Marqueur indiquant si le message associé est un événement.
    Valeurs valides :
    • vrai : le message est un événement.
    • faux : le message n’est pas un événement.

    Valeur par défaut : false
    <json_string>.isInternalMessage Booléen
    Marqueur indiquant s’il s’agit d’un message interne et ne doit pas être affiché à l’appelant.

    Les transcriptions sont généralement considérées comme des messages internes et n’apparaissent que pour l’agent et non pour l’appelant. En outre, Chuchotage est utilisé lorsqu’un tiers silencieux discute avec un tiers silencieux ou est amené dans une conversation téléphonique sans que l’appelant le sache et offre des conseils à un agent. L’appelant n’entend ni ne voit ces messages, mais l’agent si.

    Valeurs valides :
    • vrai : message interne, ne pas afficher à l’appelant.
    • faux : Pas un message interne, affichage à l’appelant.

    Valeur par défaut : false
    <json_string>.ScoreLoudness Numéro
    Mesure du volume de la parole d’un client ou d’un agent pendant un appel.

    Contact Lens affiche une analyse de la conversation qui montre où ils peuvent parler fort et avoir un sentiment négatif.

    Valeur par défaut : nul
    <json_string>.identifiant_participant Chaîne
    Requis. Participant associé au message.
    Valeurs valides :
    • AGENT
    • CLIENT
    <json_string>.sentiment Chaîne
    Sentiment du message.

    Cette valeur est générée par un fournisseur tiers. En fonction des paramètres de configuration de l’instance ServiceNow , cette valeur est ensuite traduite en positif, négatif ou neutre et est stockée dans l’enregistrement de conversation et d’interaction.

    Valeurs valides :
    • NÉGATIF
    • NEUTRE
    • POSITIF

    Valeur par défaut : nul
    Tableau 2. Renvoie
    Type Description
    Chaîne Message décrivant les résultats de l’appel.
    Chaîne En cas de réussite, sys_id de l’enregistrement du message d’interaction vocale qui a été créé.

    Si une erreur s’est produite, un message d’erreur décrivant la raison de l’échec.

    Table : Message de conversation de la transcription vocale [sys_cs_message_voice_transcript]

    L’exemple suivant montre comment ajouter des messages à un enregistrement d’interaction vocale existant.

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

    Sortie :

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

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

    VoiceTranscriptObject : createConversation(String interactionId, chaîne JSON)

    Crée un enregistrement de conversation dans la table de conversation [sys_cs_conversation] pour l’interaction spécifiée.

    Tableau 3. Paramètres
    Nom Type Description
    interactionId Chaîne Sys_id de l’enregistrement d’interaction pour lequel créer un enregistrement de conversation. Cette valeur est renvoyée par la VoiceTranscriptObject : startVoiceInteraction(String JSON) méthode et stockée dans la table Interaction [interaction].
    <json_string> Chaîne Chaîne JSON des paramètres d’entrée.
    "<json_string>": {
  "agentId": "String",
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userId": "String"
    <json_string>.agentId Chaîne Identificateur unique de l’agent auquel affecter l’interaction vocale.

    Par défaut : aucune. Affecté au prochain agent disponible.

    Table : dans le champ ID de l’utilisateur de la table Utilisateur [sys_user].
    <json_string>.numéronumérotéléphone de l’appelant Chaîne Numéro de téléphone de rappel de l’appelant. Il s’agit du numéro que l’agent utilise pour joindre l’appelant en cas d’interruption de l’appel.

    Format : conforme à la norme E.164

    Par défaut : aucun
    <json_string>.clientSessionId Chaîne Identificateur unique d’un enregistrement dans un système externe utilisé pour suivre cet appel téléphonique. Ces informations relient les enregistrements entre les deux systèmes.

    Par défaut : aucun
    <json_string>.inboundId Chaîne Identificateur unique du fournisseur d’application pour le service vocal.

    Par défaut : Extraire de la messagerie instantanée

    Table : dans le champ ID entrante de la table Application du canal du fournisseur [sys_cs_provider_application].
    <json_string>.userId Chaîne Obligatoire. Numéro de téléphone de l’appelant qui a passé l’appel associé à la transaction vocale.

    Format : défini par le logiciel qui a créé le script de conversation vocale. Généralement conforme à la norme E.164.
    Tableau 4. Renvoie
    Type Description
    Chaîne En cas de réussite, renvoie le sys_id de l’enregistrement de conversation nouvellement créé. Si une erreur se produit, renvoie un message d’erreur détaillé.

    Table : Conversation [sys_cs_conversation]

    L’exemple de code suivant montre comment créer un nouvel enregistrement de conversation à l’aide de cette méthode.

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

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

    Sortie :

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

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

    VoiceTranscriptObject : endVoiceInteraction(String interactionId, chaîne JSON)

    Met fin à l’interaction vocale spécifiée. Une fois appelé, aucun message vocal supplémentaire n’est traduit et stocké pour la conversation téléphonique.

    Tableau 5. Paramètres
    Nom Type Description
    interactionId Chaîne Sys_id de l’enregistrement d’interaction dont l’interaction vocale doit mettre fin. Situé dans la table Interaction [interaction].
    <json_string> Chaîne JSON Facultatif. Paramètres contenant des informations supplémentaires sur les interactions vocales.
    "<json_string>": {
  "recordingURL": "String"
}
    <json_string>.recordingURL Chaîne Facultatif. URL de l’enregistrement vocal d’origine.

    Si elle est configurée à cette fin, cette URL s’affiche dans Espace de travail d'agent.

    Par défaut : aucun
    Tableau 6. Renvoie
    Type Description
    Chaîne En cas de réussite, renvoie la valeur Réussite. Si une erreur se produit, renvoie un message d’erreur détaillé.

    L’exemple de code suivant montre comment mettre fin à une interaction vocale active et transmettre l’URL d’enregistrement vocal d’origine.

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

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

    Sortie :

    // Success
Success

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

    VoiceTranscriptObject : saveVoiceConversationTranscript(String voiceConversationJson)

    Enregistre les données de transcription de conversation vocale tierce dans des tables au sein d’une ServiceNow instance qui est ensuite accessible via Gestion du service client (CSM).

    Ces conversations vocales sont généralement générées à l’aide d’un logiciel de fournisseur tiers. Cette méthode analyse le JSON transmis et enregistre les données dans les tables Conversation [sys_cs_conversation], Message de conversation [sys_cs_message] et Message de conversation de transcription vocale [sys_cs_message_voice_transcript] au sein de l’instance ServiceNow . CSM accède aux informations de ces tables pour afficher les transcriptions des conversations vocales.

    Tableau 7. Paramètres
    Nom Type Description
    voiceConversationJson Chaîne JSON qui représente la conversation vocale à stocker. Ce JSON est envoyé par un autre module d’extension ServiceNow , tel qu’OpenFrame. Des fournisseurs tiers, tels qu’Amazon, envoient le JSON au module d’extension. Le module d’extension associé analyse la conversation vocale et envoie le JSON au format requis à Agent virtuel.

    Par exemple, voici un exemple de conversation 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": [] 
    } 
  ] 
}
    Tableau 8. Renvoie
    Type Description
    Chaîne Résultats de l’appel de méthode.
    Résultats de retour possibles :
    • La transcription de la conversation vocale a été enregistrée avec succès. ID de conversation : <transcript_record_sys_id>
    • Impossible d’enregistrer la transcription de la conversation vocale. Erreur de détail : <détails de l’erreur>
    • ERREUR : InteractionId est absent de la demande.
    • ERREUR : l’interaction spécifiée dans la demande a déjà été traitée.

    Cet exemple montre comment appeler la méthode saveVoiceConversationTranscript() pour enregistrer une transcription 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);

    Sortie :

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

    VoiceTranscriptObject : startVoiceInteraction(String JSON)

    Crée un enregistrement d’interaction vocale dans la table Interaction [interaction].

    Vous devez créer cet enregistrement avant d’essayer d’enregistrer des messages vocaux transcrits. Vous pouvez également utiliser cette méthode pour affecter un appel à un agent spécifique en transmettant l’ID d’utilisateur spécifique.

    Tableau 9. Paramètres
    Nom Type Description
    <json_string> Chaîne Chaîne JSON des paramètres d’entrée.
    "<json_string>": {
  "agentId": "String",
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userId": "String"
    <json_string>.agentId Chaîne Identificateur unique de l’agent auquel affecter l’interaction vocale.

    Par défaut : aucune. Affecté au prochain agent disponible.

    Table : dans le champ ID de l’utilisateur de la table Utilisateur [sys_user].
    <json_string>.numéronumérotéléphone de l’appelant Chaîne Numéro de téléphone de rappel de l’appelant. Il s’agit du numéro que l’agent utilise pour joindre l’appelant en cas d’interruption de l’appel.

    Format : conforme à la norme E.164

    Par défaut : aucun
    <json_string>.clientSessionId Chaîne Identificateur unique d’un enregistrement dans un système externe utilisé pour suivre cet appel téléphonique. Ces informations relient les enregistrements entre les deux systèmes.

    Par défaut : aucun
    <json_string>.inboundId Chaîne Identificateur unique du fournisseur d’application pour le service vocal.

    Par défaut : Extraire de la messagerie instantanée

    Table : dans le champ ID entrante de la table Application du canal du fournisseur [sys_cs_provider_application].
    <json_string>.userId Chaîne Obligatoire. Numéro de téléphone de l’appelant qui a passé l’appel associé à la transaction vocale.

    Format : défini par le logiciel qui a créé le script de conversation vocale. Généralement conforme à la norme E.164.
    Tableau 10. Renvoie
    Type Description
    Chaîne Résultats de l’appel de méthode.
    Résultats de retour possibles :
    • Réussite : {"interactionId » :"<interaction_sys_id> »,"status » :"SUCCESS"}
    • Erreur : {"error » :"<error message> »,"status » :"FAILED"}

    L’exemple de code suivant montre comment créer un enregistrement d’interaction vocale.

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

    Sortie :

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

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