VoiceTranscriptObject - com escopo

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 11 min. de leitura

    • A API programável VoiceTranscriptObject fornece métodos para salvar dados de transcrição de conversas de voz de terceiros em uma tabela dentro de uma instância ServiceNow.

    Ao chamar a classe VoiceTranscriptObject, use o identificador de namespace sn_cs.

    Disponibilidade

    Esta API está disponível no sistema ServiceNow de base. O acesso é restrito pelas ACLs impostas nas tabelas Interação [interação] e Conversação [sys_cs_conversation].

    VoiceTranscriptObject - addVoiceInteractionMessage(cadeia de caracteres interactionId, cadeia de caracteres JSON)

    Adiciona as mensagens especificadas ao registro de transação de voz especificado.

    Você pode chamar este endpoint várias vezes durante a transcrição em tempo real da chamada ou passar todas as mensagens em uma única chamada se estiver transcrevendo a chamada para fins de histórico. Se você estiver processando uma conversa em tempo real, deverá chamar este endpoint com frequência, para que as mensagens apareçam em Espaço do agente em tempo hábil. As mensagens são ordenadas com base em suas horas de início e término em relação ao início da chamada.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    interactionId Cadeia de caracteres Sys_id do registro de interação ao qual as mensagens especificadas serão adicionadas. Este valor é retornado pelo método VoiceTranscriptObject - startVoiceInteraction(cadeia de caracteres Json) e armazenado na tabela Interação [interação].
    <json_string> Cadeia de caracteres (matriz de objetos)
    Lista de mensagens a serem anexadas à interação de voz especificada.
    "<json_string>":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "Number",
    "participantId": "String",
    "sentiment": "String"
  }
]
    <json_string>.atributos Matriz de objetivos
    Pares de chave-valor a serem associados à interação de voz.

    Podem ser qualquer tipo de objeto de dados, de objetos simples a objetos compostos complexos. Eles são usados como identificadores exclusivos ao invocar APIs do Amazon Web Services.

    Padrão: nenhum
    <json_string>.beginOffsetMilhões Longa Obrigatório. Compensação de tempo entre o início da interação de voz e o início da mensagem associada. Por exemplo: "beginOffsetMillis": 2650.

    Unidade: Milissegundos
    <json_string>.conteúdo Cadeia de caracteres Obrigatório. Texto da mensagem a ser adicionada à interação de voz.
    <json_string>.endOffsetMilhões Longa Obrigatório. Compensação de tempo entre o início da interação de voz e o fim da mensagem. Por exemplo: "endOffsetMillis": 9380.

    Unidade: Milissegundos
    <json_string>.id Cadeia de caracteres UUID da mensagem da origem desta conversa de voz, como para AmazonConnect. Define o valor da coluna ID da mensagem de origem.

    Padrão: nenhum
    <json_string>.isEvent Booliano
    Definido pelo Amazon Connect, mas não usado atualmente pelo método. Sinalizador que indica se a mensagem associada é um evento.
    Valores válidos:
    • verdadeiro: a mensagem é um evento.
    • falso: a mensagem não é um evento.

    Padrão: falso
    <json_string>.isInternalMessage Booliano
    Sinalizador que indica se esta é uma mensagem interna e não deve ser mostrada ao solicitante.

    As transcrições são normalmente consideradas mensagens internas e só aparecem para o agente e não para o solicitante. Além disso, o Sussurro do agente é usado quando um terceiro silencioso está conversando ou é introduzido em uma conversa telefônica sem que o solicitante saiba e oferece aconselhamento a um agente. O chamador não ouve ou vê essas mensagens, mas o agente sim.

    Valores válidos:
    • verdadeiro: mensagem interna, não é exibida para o solicitante.
    • falso: não é uma mensagem interna, exibe para o solicitante.

    Padrão: falso
    <json_string>.pontuação de volume Número
    Medição do volume de voz de um cliente ou agente durante uma chamada.

    A Lente de contato exibe uma análise da conversa que mostra onde eles podem estar falando alto e ter um sentimento negativo.

    Padrão: nulo
    <json_string>.participantId Cadeia de caracteres
    Obrigatório. Participante associado à mensagem.
    Valores válidos:
    • CLIENTE
    • AGENTE
    <json_string>.sentimento Cadeia de caracteres
    Sentimento da mensagem.

    Este valor é gerado por um provedor de terceiros. Com base nas definições de configuração da instância ServiceNow, esse valor é convertido para ser positivo, negativo ou neutro e é armazenado no registro de conversa e interação.

    Valores válidos:
    • NEGATIVO
    • NEUTRO
    • POSITIVO

    Padrão: nulo
    Tabela 2. Retorna
    Tipo Descrição
    Cadeia de caracteres Mensagem que descreve os resultados da chamada.
    Cadeia de caracteres Se for bem-sucedido, sys_id do registro da mensagem de interação de voz que foi criado. Localizado na tabela Mensagem de conversa de transcrição de voz [sys_cs_message_voice_transscript].

    Se ocorreu um erro, uma mensagem de erro descrevendo o motivo da falha.

    O exemplo a seguir mostra como adicionar mensagens a um registro de interação de voz existente.

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

    Saída:

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

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

    VoiceTranscriptObject - createConversation(cadeia de caracteres interactionId, cadeia de caracteres Json)

    Cria um registro de conversa na tabela Conversation [sys_cs_conversation] para a interação especificada.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    interactionId Cadeia de caracteres Sys_id do registro de interação para o qual um registro de conversa será criado. Este valor é retornado pelo método VoiceTranscriptObject - startVoiceInteraction(cadeia de caracteres Json) e armazenado na tabela Interação [interação].
    <json_string> Cadeia de caracteres Cadeia de caracteres JSON dos parâmetros de entrada.
    "<json_string>": {
  "agentId": "String",
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userId": "String"
    <json_string>.agentId Cadeia de caracteres Identificador exclusivo do agente ao qual a interação de voz será atribuída. Localizado no campo ID do usuário na tabela Usuário [sys_user].

    Padrão: nenhum. Atribuído ao próximo agente disponível.
    <json_string>.CallerPhoneNumber Cadeia de caracteres Número de telefone de retorno de chamada do solicitante. Este é o número que o agente usa para entrar em contato com o chamador, caso a chamada caia.

    Formato: compatível com o padrão E.164

    Padrão: nenhum
    <json_string>.clientSessionId Cadeia de caracteres Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica. Essas informações vinculam os registros entre os dois sistemas.

    Padrão: nenhum
    <json_string>.inboundId Cadeia de caracteres Identificador exclusivo do provedor de aplicações para o serviço de voz. Localizado no campo ID de entrada na tabela Aplicação de canal do provedor [sys_cs_provider_application].

    Padrão: extrair do bate-papo
    <json_string>.userId Cadeia de caracteres Obrigatório. Número de telefone do chamador que fez a chamada associada à transação de voz.

    Formato: definido pelo software que criou o script de conversa de voz. Normalmente compatível com o padrão E.164.
    Tabela 4. Retorna
    Tipo Descrição
    Cadeia de caracteres Se for bem-sucedido, retornará o sys_id do registro de conversa recém-criado. Localizado na tabela Conversation [sys_cs_conversation]. Se ocorrer um erro, retornará uma mensagem de erro detalhada.

    O exemplo de código a seguir mostra como criar um novo registro de conversa usando este método.

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

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

    Saída:

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

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

    VoiceTranscriptObject - endVoiceInteraction(cadeia de caracteres interactionId, cadeia de caracteres JSON)

    Encerra a interação de voz especificada. Depois de chamado, nenhuma mensagem de voz adicional é traduzida e armazenada para a conversa telefônica.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    interactionId Cadeia de caracteres Sys_id do registro de interação cuja interação de voz será encerrada. Localizado na tabela Interação [interação].
    <json_string> Cadeia de caracteres JSON Opcional. Parâmetros que contêm informações adicionais sobre as interações de voz.
    "<json_string>": {
  "recordingURL": "String"
}
    <json_string>.recordingURL Cadeia de caracteres Opcional. URL onde a gravação de voz original está localizada.

    Se configurado para isso, este URL aparecerá em Espaço do agente.

    Padrão: nenhum
    Tabela 6. Retorna
    Tipo Descrição
    Cadeia de caracteres Se for bem-sucedido, retornará Success. Se ocorrer um erro, retornará uma mensagem de erro detalhada.

    O exemplo de código a seguir mostra como encerrar uma interação de voz ativa e passar o URL de gravação de voz original.

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

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

    Saída:

    // Success
Success

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

    VoiceTranscriptObject - saveVoiceConversationTranscript (cadeia de caracteres "voiceConversationJson")

    Salva dados de transcrição de conversas de voz de terceiros em tabelas em uma instância ServiceNow que pode ser acessada por meio de Customer Service Management (CSM).

    Essas conversas de voz são normalmente geradas usando software de fornecedor de terceiros. Este método analisa o JSON passado e salva os dados nas tabelas Conversa [sys_cs_conversation], Mensagem de conversa [sys_cs_message] e Mensagem de conversa de transcrição de voz [sys_cs_message_voice_transscript] na instância ServiceNow. O CSM acessa as informações nessas tabelas para exibir as transcrições de conversas de voz.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    vozConversationJson Cadeia de caracteres JSON que representa a conversa de voz a ser armazenada. Este JSON é enviado por outro plug-in ServiceNow, como OpenFrame. Fornecedores de terceiros, como a Amazon, enviam o JSON para o plug-in. O plug-in associado analisa a conversa de voz e envia o JSON no formato necessário para Virtual Agent.

    Por exemplo, a seguir está um exemplo de uma conversa do 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": [] 
    } 
  ] 
}
    Tabela 8. Retorna
    Tipo Descrição
    Cadeia de caracteres Resultados da chamada de método.
    Possíveis resultados de retorno:
    • A transcrição da conversa de voz foi salva com sucesso. ID da conversa:<transcript_record_sys_id>
    • Não foi possível salvar a transcrição da conversa de voz. Erro de detalhe:<error details>
    • ERRO: InteractionId está ausente na solicitação.
    • ERRO: a interação especificada na solicitação já foi processada.

    Este exemplo mostra como chamar o método saveVoiceConversationTranscript() para salvar uma transcrição do 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);

    Saída:

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

    VoiceTranscriptObject - startVoiceInteraction(cadeia de caracteres Json)

    Cria um registro de interação de voz na tabela Interação [interação].

    Você deve criar este registro antes de tentar salvar mensagens de voz transcritas. Você também pode usar este método para atribuir uma chamada a um agente específico, passando o ID de usuário específicoir.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    <json_string> Cadeia de caracteres Cadeia de caracteres JSON dos parâmetros de entrada.
    "<json_string>": {
  "agentId": "String",
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userId": "String"
    <json_string>.agentId Cadeia de caracteres Identificador exclusivo do agente ao qual a interação de voz será atribuída. Localizado no campo ID do usuário na tabela Usuário [sys_user].

    Padrão: nenhum. Atribuído ao próximo agente disponível.
    <json_string>.CallerPhoneNumber Cadeia de caracteres Número de telefone de retorno de chamada do solicitante. Este é o número que o agente usa para entrar em contato com o chamador, caso a chamada caia.

    Formato: compatível com o padrão E.164

    Padrão: nenhum
    <json_string>.clientSessionId Cadeia de caracteres Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica. Essas informações vinculam os registros entre os dois sistemas.

    Padrão: nenhum
    <json_string>.inboundId Cadeia de caracteres Identificador exclusivo do provedor de aplicações para o serviço de voz. Localizado no campo ID de entrada na tabela Aplicação de canal do provedor [sys_cs_provider_application].

    Padrão: extrair do bate-papo
    <json_string>.userId Cadeia de caracteres Obrigatório. Número de telefone do chamador que fez a chamada associada à transação de voz.

    Formato: definido pelo software que criou o script de conversa de voz. Normalmente compatível com o padrão E.164.
    Tabela 10. Retorna
    Tipo Descrição
    Cadeia de caracteres Resultados da chamada de método.
    Possíveis resultados de retorno:
    • Sucesso: {"interactionId":"<interaction_sys_id> ","status":"SUCESSO"}
    • Erro: {"erro":"<error message> ","status":"FAILED"}

    O exemplo de código a seguir mostra como criar um registro de interação de voz.

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

    Saída:

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

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