API do recurso de interação de voz

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 19 min. de leitura

    • A API de interação de voz permite 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 do agente e pesquisa enquanto conversam com um solicitante. As mensagens transcritas são mantidas na tabela Mensagem de conversa [sys_cs_message].

    Mensagens transcritas no Agent Workspace

    Fluxo de chamada

    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ócios 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 [interaction].
    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á ligar para 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 manter as 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 base ServiceNow. O acesso é restrito pelas ACLs impostas nas tabelas Interação [interação] e Conversa [sys_cs_conversation].

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

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

    Formato de URL

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

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

    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. Especifique este valor somente 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. Localizado na tabela Interação [interaction] e passado de volta pelo endpoint Recurso de interação de voz - POST /cs/voice-interactions.

    Tipo de dados: cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum
    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
    state Obrigatório. Estado da interação por 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    Tabela 6. Códigos de status
    Código de 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 qualquer mensagem de voz transcrita. 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 de URL

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

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

    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. Especifique este valor somente 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
    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. Localizado no campo ID do usuário na tabela Usuário [sys_user].

    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: padrão E.164 compatível

    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. Localizado no campo ID de entrada na tabela da aplicação de canal do provedor [sys_cs_provider_application].

    Tipo de dados: cadeia de caracteres

    Padrão: extraído do bate-papo
    userId Obrigatório. Número de telefone do solicitante 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    Tabela 12. Códigos de status
    Código de 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. Localizado na tabela Interação [interação].
    Use este sys_id quando:

    Tipo de dados: cadeia de caracteres

    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 Conversa [sys_cs_conversation] para a interação especificada.

    Formato de URL

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

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

    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. Especifique este valor somente 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 [interaction].

    Tipo de dados: cadeia de caracteres
    Tabela 14. Parâmetros de consulta
    Nome Descrição
    Nenhum
    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. Localizado no campo ID do usuário na tabela Usuário [sys_user].

    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: padrão E.164 compatível

    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. Localizado no campo ID de entrada na tabela da aplicação de canal do provedor [sys_cs_provider_application].

    Tipo de dados: cadeia de caracteres

    Padrão: extrair do bate-papo
    userId Obrigatório. Número de telefone do solicitante 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    Tabela 18. Códigos de status
    Código de 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. Localizado na 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 o software do 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á ligar para 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 de 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

    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. Especifique este valor somente 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 [interaction].

    Tipo de dados: cadeia de caracteres
    Tabela 20. Parâmetros de consulta
    Nome Descrição
    Nenhum
    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.

    Eles 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>.beginOffsetMilis 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>.endOffsetMilis Obrigatório. Compensação de tempo entre o início da interação de voz e o final 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 do 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.
    • false: 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 aparecem somente para o agente e não para o solicitante. Além disso, a Conversa particular entre agentes é usada quando um terceiro silencioso está em um bate-papo ou é chamado para 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 as vê.

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

    Tipo de dados: booliano

    Padrão: falso
    <json_string>.loudnessScore
    Medição de quão alto um cliente ou agente está falando durante uma chamada.

    A Lente de contato exibe uma análise da conversa que mostra onde ela pode 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:
    • CLIENTE
    • AGENTE

    Tipo de dados: cadeia de caracteres
    <json_string>.sentimento
    Sentimento da mensagem.

    Este valor é gerado por um provedor terceirizado. Com base nas definições de configuração da instância ServiceNow, este valor é convertido em 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    Tabela 24. Códigos de status
    Código de 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 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_Transcript].

    Tipo de dados: cadeia de caracteres

    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 de URL

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

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

    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. Especifique este valor somente 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
    Tabela 27. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    conversa iniciada Hora de início da conversa. Localizado na tabela Interação [interação].

    Tipo de dados: cadeia de caracteres

    Formato: AAAA-MM-DD HH:MM:SS
    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 [interaction].

    Tipo de dados: cadeia de caracteres
    origem Nome do canal que criou originalmente a transcrição de interação da 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.

    Eles 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.beginOffsetMilis 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.endOffsetMilis Obrigatório. Compensação de tempo entre o início da interação de voz e o final 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 do ID da mensagem de origem.

    Tipo de dados: cadeia de caracteres

    Padrão: Nenhum
    transcrição.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.
    • false: a mensagem não é um evento.

    Tipo de dados: booliano

    Padrão: falso
    Transcript.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 aparecem somente para o agente e não para o solicitante. Além disso, a Conversa particular entre agentes é usada quando um terceiro silencioso está em um bate-papo ou é chamado para 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 as vê.

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

    Tipo de dados: booliano

    Padrão: falso
    transcrição.pontuação de volume
    Medição de quão alto um cliente ou agente está falando durante uma chamada.

    A Lente de contato exibe uma análise da conversa que mostra onde ela pode 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:
    • CLIENTE
    • AGENTE

    Tipo de dados: cadeia de caracteres
    transcrição.sentimento
    Sentimento da mensagem.

    Este valor é gerado por um provedor terceirizado. Com base nas definições de configuração da instância ServiceNow, este valor é convertido em 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    Tabela 30. Códigos de status
    Código de 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. Localizado na tabela Conversa [sys_cs_message_conversation].

    Tipo de dados: cadeia de caracteres

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