API de recurso de interação de voz

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 19 min. de leitura

    • A API de interação de voz fornece endpoints para transcrever e armazenar interações de voz entre agentes e chamadores durante uma conversa telefônica. Ele funciona em conjunto com os bate-papos Virtual Agent e Atendente.

    Você pode usar esta API para persistir mensagens transcritas de uma chamada telefônica em andamento em tempo real ou para transcrever e armazenar uma gravação de conversa de voz existente para fins históricos. As mensagens transcritas aparecem em Espaço do agente, permitindo que os agentes aproveitem recursos como assistência ao agente e pesquisa enquanto conversam com um chamador. As mensagens transcritas são persistentes na tabela Mensagem de conversa [sys_cs_message].

    Mensagens transcritas no Espaço do agente

    Fluxo de chamadas

    O fluxo de chamada a seguir mostra como usar a API de interação de voz para criar um registro de interação de voz, transcrever e armazenar as mensagens nessa conversa de voz e fechar o registro da conversa de voz. Você também pode usar regras de negócio e outros scripts para executar essa funcionalidade. No entanto, esse tipo de implementação não é abordado nesta seção.
    1. Primeiro, chame o endpoint Recurso de interação de voz - POST /cs/voice-interactions para criar um registro de interação de voz na tabela Interação [interação].
    2. Em seguida, chame o endpoint Recurso de interação de voz - POST /cs/voice-interactions/{interactionId}/messages para armazenar mensagens traduzidas da conversa de voz na tabela Mensagem de conversa. 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. Ao processar uma gravação para fins históricos, você pode passar todas as mensagens em uma única chamada de endpoint.
    3. Quando terminar de persistir nas mensagens de voz, chame o endpoint Recurso de interação de voz - PATCH /cs/voice-interactions/{interactionId}/state para encerrar a captura e fechar o registro de interação de voz.

    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].

    Recurso de interação de voz - PATCH /cs/voice-interactions/{interactionId}/state

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

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/cs/voice-interactions/{interactionId}/state

    URL padrão: /api/now/v1/cs/voice-interactions/{interactionId}/state

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário Serviço REST com script.

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    interactionId Sys_id do registro de interação cuja interação de voz será encerrada. Retransmitido pelo endpoint Recurso de interação de voz - POST /cs/voice-interactions.

    Tipo de dados: cadeia de caracteres

    Tabela: interação [interação]
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    gravandoURL URL onde a gravação de voz original está localizada.

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

    Tipo de dados: cadeia de caracteres

    Padrão: nenhum
    estado Obrigatório. Estado da interação de voz.

    Somente valor compatível: closed_complete

    Tipo de dados: cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. JSON malformado ou parâmetros obrigatórios não aprovados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    resultado Status da operação.
    Valores possíveis:
    • Êxito
    • Reprovado

    Se um erro for encontrado, uma mensagem que descreve o erro também será retornada. Se o erro estiver na instância ServiceNow, a instância registrará em log o rastreamento de pilha associado.

    Solicitação de cURL

    O exemplo a seguir mostra como encerrar uma instância de voz.

    curl "http://instance.servicenow.com/api/now/v1/ cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/state" \ 
--request PATCH \
--header "Content-Type: application/json" \
--header "Accept:application/json" \
--user 'username':'password' \
-d {
  "state": "closed_complete",
  "recordingURL": "https: //zoom_instance/rec/QbF7XmPFHPlX1LG"
}’

    Resposta:

    {
  "result": "Success"
}

    Recurso de interação de voz - POST /cs/voice-interactions

    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 endpoint para atribuir uma chamada a um agente específico, passando seu ID de usuário específico.

    Formato da URL

    URL com controle de versões: /api/now/{api_version}/cs/voice-interactions

    URL padrão: /api/now/v1/cs/voice-interactions

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário Serviço REST com script.

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    agentId Identificador exclusivo do agente ao qual a interação de voz será atribuída.

    Tipo de dados: cadeia de caracteres

    Padrão: invocar Virtual Agent
    callerPhoneNumber 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.

    Tipo de dados: cadeia de caracteres

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

    Padrão: nenhum
    clientSessionId 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.

    Tipo de dados: cadeia de caracteres

    Padrão: nenhum
    inboundId Identificador exclusivo do provedor de aplicações para o serviço de voz.

    Tipo de dados: cadeia de caracteres

    Padrão: extraído do bate-papo
    userId Obrigatório. Número de telefone do chamador que fez a chamada associada à transação de voz.

    Tipo de dados: cadeia de caracteres

    Formato: definido pelo software que criou o script de conversa de voz. Normalmente compatível com o padrão E.164.

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 12. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. JSON malformado ou parâmetros obrigatórios não aprovados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    interactionId Sys_id do registro de interação de voz recém-criado.
    Use este sys_id quando:

    Tipo de dados: cadeia de caracteres

    Tabela: interação [interação]

    Solicitação de cURL

    O exemplo de código a seguir mostra como iniciar uma interação de voz e transferir a chamada para um agente específico.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions" \ 
--request POST \ 
--header "Accept:application/json" \ 
--user 'username':'password' \ 
--header "Content-Type: application/json"\ 
-d '{ 
  "userId": "+14089178877",
  "agentId": "beth.anglin",
  "callerPhoneNumber": "+14089178878",
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z"
}'

    Resposta:

    {
  "result": {
    "interactionId": "4462cb4753751110b6e8ddeeff7b12ca"
  }
}

    Recurso de interação de voz - POST /cs/voice-interactions/{interactionId}/conversation

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

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/cs/voice-interactions/{interactionId}/conversation

    URL padrão: /api/now/v1/cs/voice-interactions/{interactionId}/conversation

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário Serviço REST com script.

    Parâmetros de solicitação compatíveis

    Tabela 13. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    interactionId Sys_id do registro de interação para o qual o registro de conversa será criado. Este valor é retornado pelo endpoint Recurso de interação de voz - POST /cs/voice-interactions e armazenado na tabela Interação [interação].

    Tipo de dados: cadeia de caracteres
    Tabela 14. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 15. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    agentId Identificador exclusivo do agente ao qual a interação de voz será atribuída.

    Tipo de dados: cadeia de caracteres

    Padrão: invocar Virtual Agent
    callerPhoneNumber 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.

    Tipo de dados: cadeia de caracteres

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

    Padrão: nenhum
    clientSessionId 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.

    Tipo de dados: cadeia de caracteres

    Padrão: nenhum
    inboundId Identificador exclusivo do provedor de aplicações para o serviço de voz.

    Tipo de dados: cadeia de caracteres

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

    Tipo de dados: cadeia de caracteres

    Formato: definido pelo software que criou o script de conversa de voz. Normalmente compatível com o padrão E.164.

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 16. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 17. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 18. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. JSON malformado ou parâmetros obrigatórios não aprovados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    conversationId Sys_id do registro de conversa recém-criado.

    Tipo de dados: cadeia de caracteres

    Tabela: conversa [sys_cs_conversation]

    Solicitação de cURL

    O exemplo de código a seguir mostra como chamar este endpoint.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/7662cb4721751ea0b6e8dda1b27b131f/conversation" \  
--request POST \  
--header "Accept:application/json" \  
--user 'username':'password' \  
--header "Content-Type: application/json"\  
-d '{  
  "userId": "+14089178877", 
  "agentId": "admin@example.com", 
  "callerPhoneNumber": "+14089178878", 
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z" 
}'

    Resposta:

    { 
  "result": "a47e1afdb7471110b6e8bc15ae11a934" 
}

    Recurso de interação de voz - POST /cs/voice-interactions/{interactionId}/messages

    Adiciona as mensagens de conversas de voz especificadas ao registro de transação de voz especificado. Essas mensagens são normalmente geradas usando software de fornecedor de terceiros. Atualmente, somente o Amazon Connect é compatível.

    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.

    Formato da URL

    URL com controle de versões: /api/now/{api_version}/cs/voice-interactions/{interactionId}/messages

    URL padrão: /api/now/v1/cs/voice-interactions/{interactionId}/messages

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário Serviço REST com script.

    Parâmetros de solicitação compatíveis

    Tabela 19. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    interactionId Sys_id do registro de interação ao qual as mensagens especificadas serão adicionadas. Este valor é retornado pelo endpoint Recurso de interação de voz - POST /cs/voice-interactions e armazenado na tabela Interação [interação].

    Tipo de dados: cadeia de caracteres
    Tabela 20. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 21. Parâmetros do corpo da solicitação (Amazon Connect)
    Nome Descrição
    <json_string>
    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
    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.

    Tipo de dados: matriz de objetos

    Padrão: nenhum
    <json_string>.beginOffsetMilhões 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.

    Tipo de dados: longo

    Unidade: Milissegundos
    <json_string>.conteúdo Obrigatório. Texto da mensagem a ser adicionada à interação de voz.

    Tipo de dados: cadeia de caracteres
    <json_string>.endOffsetMilhões Obrigatório. Compensação de tempo entre o início da interação de voz e o fim da mensagem. Por exemplo: "endOffsetMillis": 9380.

    Tipo de dados: longo

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

    Tipo de dados: cadeia de caracteres

    Padrão: nenhum
    <json_string>.isEvent
    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.

    Tipo de dados: booliano

    Padrão: falso
    <json_string>.isInternalMessage
    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.

    Tipo de dados: booliano

    Padrão: falso
    <json_string>.pontuação de volume
    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.

    Tipo de dados: número

    Intervalo: -1,0 (negativo) a 1,0 (positivo)

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

    Tipo de dados: cadeia de caracteres
    <json_string>.sentimento
    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

    Tipo de dados: cadeia de caracteres

    Padrão: nulo

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 22. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 23. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 24. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. JSON malformado ou parâmetros obrigatórios não aprovados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    resultado Mensagem que descreve os resultados da chamada.

    Tipo de dados: cadeia de caracteres
    ID da conversa Sys_id do registro de mensagem de interação de voz que foi criado.

    Tipo de dados: cadeia de caracteres

    Tabela: mensagem de conversa de transcrição de voz [sys_cs_message_voice_transscript]

    Solicitação de cURL

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

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/messages" \ 
--request POST \
--header "Accept:application/json" \
--header "Content-Type: application/json"\ 
--user 'username':'password' \
-d ' [ 
  { 
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 10000,  
    "content": "This is John. How can I help you?",  
    "endOffsetMillis": 15000,  
    "id": "954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8",  
    "participantId": "AGENT",  
    "sentiment": "NEUTRAL",  
    "loudnessScore": "null",  
    "attributes": [{  
      "key": "key1",  
      "value": "value1"  
      }, {  
      "key": "key2",  
      "value": "value2"  
    }] 
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 20000,  
    "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"  
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 30000,  
    "content": "I am sorry to hear that",  
    "endOffsetMillis": 35000,  
    "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",  
    "participantId": "AGENT",  
    "sentiment": "NEGATIVE",  
 
  },  
  {  
    "isEvent":"false",
    "isInternalMessage":"false",
    "beginOffsetMillis":40000,
    "content":"Can you help me with my insurance? My ssn is 123-12-1234",
    "endOffsetMillis":45000,
    "id":"ab09b3b6-23fd-4e41-be05-6b2b53c19059",
    "participantId":"CUSTOMER",
    "sentiment":"NEUTRAL" 
  },  
  {  
    "isEvent":"False",
    "isInternalMessage":"False",
    "beginOffsetMillis":50000, 
    "content":"Of course, let me check your account",
    "endOffsetMillis":55000,
    "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",
    "participantId":"AGENT",
    "sentiment":"NEUTRAL" 
  }  
]'

    Resposta:

    { 
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2" 
}

    Recurso de interação de voz - POST /cs/voice-interactions/transscript

    Adiciona mensagens a uma interação de voz existente após a conclusão de uma chamada. Você pode usar esta API para anexar mensagens transcritas de uma chamada de voz entre um agente e o solicitante.

    Formato da URL

    URL com controle de versões: /api/now/{api_version}/cs/voice-interactions/{interactionId}/transscript

    URL padrão: /api/now/v1/cs/voice-interactions/{interactionId}/transscript

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário Serviço REST com script.

    Parâmetros de solicitação compatíveis

    Tabela 25. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    Tabela 26. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 27. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    conversaIniciada Hora de início da conversa.

    Tipo de dados: cadeia de caracteres

    Formato: AAAA-MM-DD HH:MM:SS

    Tabela: interação [interação]
    interactionId Sys_id do registro de interação ao qual as mensagens especificadas serão adicionadas. Este valor é retornado pelo endpoint Recurso de interação de voz - POST /cs/voice-interactions.

    Tipo de dados: cadeia de caracteres

    Tabela: interação [interação]
    Fonte Nome do canal que criou originalmente a transcrição de interação de conversa.

    Atualmente, o único valor compatível é o Amazon Connect.

    Tipo de dados: cadeia de caracteres
    transcrição Lista de mensagens a serem anexadas à interação de voz especificada.
    "transcript":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "String",
    "participantId": "String",
    "sentiment": "String"
  }
]

    Tipo de dados: matriz de objetos
    transcrição.atributos
    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.

    Tipo de dados: matriz de objetos

    Padrão: nenhum
    transcrição.beginOffsetMilhões 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.

    Tipo de dados: longo

    Unidade: Milissegundos
    transcrição.conteúdo Obrigatório. Texto da mensagem a ser adicionada à interação de voz.

    Tipo de dados: cadeia de caracteres
    transcrição.endOffsetMilhões Obrigatório. Compensação de tempo entre o início da interação de voz e o fim da mensagem. Por exemplo: "endOffsetMillis": 9380.

    Tipo de dados: longo

    Unidade: Milissegundos
    transcript.id UUID da mensagem da origem desta conversa de voz, como para AmazonConnect. Define o valor da coluna ID da mensagem de origem.

    Tipo de dados: cadeia de caracteres

    Padrão: nenhum
    transcrição.éEvento
    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.

    Tipo de dados: booliano

    Padrão: falso
    transcrição.éMensagemInterna
    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.

    Tipo de dados: booliano

    Padrão: falso
    transcrição.pontuaçãodevolume
    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.

    Tipo de dados: número

    Intervalo: -1,0 (negativo) a 1,0 (positivo)

    Padrão: nulo
    transcrição.participantId
    Obrigatório. Participante associado à mensagem.
    Valores válidos:
    • AGENTE
    • CLIENTE

    Tipo de dados: cadeia de caracteres
    transcrição.sentimento
    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

    Tipo de dados: cadeia de caracteres

    Padrão: nulo

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 28. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 29. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 30. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. JSON malformado ou parâmetros obrigatórios não aprovados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    resultado Mensagem que descreve os resultados da chamada.

    Tipo de dados: cadeia de caracteres
    ID da conversa Sys_id da tabela de conversa de voz em que as mensagens foram anexadas.

    Tipo de dados: cadeia de caracteres

    Tabela: conversa [sys_cs_message_conversation]

    Solicitação de cURL

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

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/transcript" \  
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type: application/json"\  
--user 'username':'password' \ 
-d ' { 
  "interactionId": "e67a6c30c7233010967a34c91dc26068", 
  "source": "Amazon Connect", 
  "conversationStarted": "2021-08-06 15:07:51", 
  "transcript": [ 
    { 
      "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 frustrated right now.", 
      "endOffsetMillis": 25000, 
      "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f", 
      "participantId": "CUSTOMER", 
      "sentiment": "NEGATIVE" 
    } 
  ] 
} ' 

    Resposta:

    {  
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2"  
}