Objeto TranscriptVoz - Com escopo

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 11 min. de leitura

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

    Ao chamar Objeto TranscriptVoz classe, use sn_cs identificador de namespace.

    Disponibilidade

    Esta API está disponível na base ServiceNow sistema. O acesso é restrito pelas ACLs impostas nas tabelas Interaction [interaction] e Conversation [sys_cs_conversation].

    Voice TranscriptObject - addVoice InteractionMessage(cadeia de caracteres interactionId, cadeia de caracteres JSON)

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

    Este endpoint pode ser chamado várias vezes durante a transcrição em tempo real da chamada ou passar todas as mensagens em uma única chamada se estiver transcriindo a chamada para fins históricos. Se você estiver processando uma conversa em tempo real, chame esse 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 nas 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 adicionar as mensagens especificadas. Este valor é retornado pelo VoiceTranscriptObject - startVoiceInteraction(cadeia de caracteres JSON) método.

    Tabela: Interação [interaction]
    <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"
  }
]
    atributos.<json_string> 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 da Amazon Web Services.

    Padrão: Nenhum
    <json_string>.beginOffsetMillis Longa Obrigatório. Deslocamento de tempo entre o início da interação de voz e o início da mensagem associada. Por exemplo: "BeginOffsetMillis": 2650.

    Unidade: Milissegundos
    conteúdo.<json_string> Cadeia de caracteres Obrigatório. Texto da mensagem a ser adicionado à interação de voz.
    OffsetMillis.endOffsetMillis <json_string> Longa Obrigatório. Deslocamento de tempo entre o início da interação de voz e o final 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
    EEvento.éEvento <json_string> 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
    Mensagem.IsInternalInternal <json_string> Booliano
    Sinalizador que indica se esta é uma mensagem interna e não deve ser mostrado ao solicitante.

    Normalmente, as transcrições são consideradas mensagens internas e aparecem somente para o agente e não para o solicitante. O Agent Whisper é usado quando um terceiro silencioso está conversando ou é levado para uma conversa telefônica sem o conhecimento do chamador e oferece conselhos a um agente. O chamador não ouve ou vê essas mensagens, mas o agente.

    Valores válidos:
    • Verdadeiro: Mensagem interna, não é exibida para o solicitante.
    • Falso: Não é uma mensagem interna, exibir para o chamador.

    Padrão: falso
    Pontuaçãode alto-falante <json_string> Número
    Medição de quanto um cliente ou agente está falando durante uma chamada.

    O Contact Lens exibe uma análise da conversa que mostra onde eles podem estar falando alto e ter um sentimento negativo.

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

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

    Valores válidos:
    • NEGATIVO
    • NEUTRO
    • POSITIVO

    Padrão: Nulo
    Tabela 2. Retornos
    Tipo Descrição
    Cadeia de caracteres Mensagem que descreve os resultados da chamada.
    Cadeia de caracteres Se bem-sucedido, sys_id do registro de mensagem de interação de voz que foi criado.

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

    Tabela: Mensagem de conversa de transcrição de voz [sys_cs_message_voice_transcrit]

    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>

    VoceTranscriptObject - createConversation (cadeia de caracteres interactionId, cadeia de caracteres JSON)

    Cria um registro de conversa na tabela Conversa [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 criar um registro de conversa. Este valor é retornado pelo VoiceTranscriptObject - startVoiceInteraction(cadeia de caracteres JSON) E armazenados na tabela Interação [interaction].
    <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"
    Id.agentId <json_string> Cadeia de caracteres Identificador exclusivo do agente ao qual atribuir a interação de voz.

    Padrão: Nenhum. Atribuído ao próximo agente disponível.

    Tabela: No campo ID do usuário da tabela Usuário [sys_user].
    CallerPhoneNumber <json_string> Cadeia de caracteres Número de telefone de retorno de chamada do chamador. Este é o número que o agente usa para entrar em contato com o solicitante caso a chamada seja descartada.

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    ClientSessionId <json_string> Cadeia de caracteres Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica em sistemas, permitindo a integração entre a ServiceNow e plataformas de terceiros (por exemplo, provedores de CCaaS).

    Padrão: Nenhum
    Id.inboundId <json_string> Cadeia de caracteres Identificador exclusivo do provedor de aplicações para o serviço de voz.

    Padrão: Extrair do bate-papo

    Tabela: No campo ID de entrada da tabela Aplicação de canal do provedor [sys_cs_provider_application].
    UserId.<json_string> 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, em conformidade com o padrão E.164.
    Tabela 4. Retornos
    Tipo Descrição
    Cadeia de caracteres Se for bem-sucedido, retornará o sys_id do registro de conversa recém-criado. Se ocorrer um erro, retornará uma mensagem de erro detalhada.

    Tabela: Conversa [sys_cs_conversation]

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

    TranscriptObject - endVoice Interaction(cadeia de caracteres interactionId, cadeia de caracteres JSON)

    Encerra a interação de voz especificada. Uma vez 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 [interaction].
    <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"
}
    URL.recordingURL <json_string> 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. Retornos
    Tipo Descrição
    Cadeia de caracteres Se bem-sucedido, retornará Sucesso . 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>

    Voice TranscriptObject - saveVoice ConversationTranscript(cadeia de caracteres voiceConversationJson)

    Salva dados de transcrição de conversa de voz de terceiros em tabelas em um ServiceNow instância 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_transcrit] em ServiceNow instância. O CSM acessa as informações nessas tabelas para exibir as transcrições da conversa de voz.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    ConversaçãoJson Cadeia de caracteres JSON que representa a conversa de voz a ser armazenada. Este JSON é enviado por outro ServiceNow Plug-in, 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.

    A seguir, há 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. Retornos
    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 detalhado: <error details>
    • InteractionId está ausente na solicitação.
    • ERRO: A interação especificada na solicitação já foi processada.

    Este exemplo mostra como chamar SalvaVoice ConversationTranscript() Método para salvar uma Amazon Transcrição do 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 Interaction [interaction].

    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 aprovando ir ID de usuário específico.

    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"
    Id.agentId <json_string> Cadeia de caracteres Identificador exclusivo do agente ao qual atribuir a interação de voz.

    Padrão: Nenhum. Atribuído ao próximo agente disponível.

    Tabela: No campo ID do usuário da tabela Usuário [sys_user].
    CallerPhoneNumber <json_string> Cadeia de caracteres Número de telefone de retorno de chamada do chamador. Este é o número que o agente usa para entrar em contato com o solicitante caso a chamada seja descartada.

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    ClientSessionId <json_string> Cadeia de caracteres Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica em sistemas, permitindo a integração entre a ServiceNow e plataformas de terceiros (por exemplo, provedores de CCaaS).

    Padrão: Nenhum
    Id.inboundId <json_string> Cadeia de caracteres Identificador exclusivo do provedor de aplicações para o serviço de voz.

    Padrão: Extrair do bate-papo

    Tabela: No campo ID de entrada da tabela Aplicação de canal do provedor [sys_cs_provider_application].
    UserId.<json_string> 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, em conformidade com o padrão E.164.
    Tabela 10. Retornos
    Tipo Descrição
    Cadeia de caracteres Resultados da chamada de método.
    Possíveis resultados de retorno:
    • "InteractionId":"<interaction_sys_id>","status":"SUCCESS"
    • "Error":"<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"}