API de recurso de interação de voz

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

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

    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 e pesquisa do agente, enquanto conversam com um chamador. As mensagens transcritas persistem 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 o. Interação de voz API para criar um registro de interação de voz, transcrever e armazenar as mensagens nessa conversa de voz e fechar o registro de 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, ligue para Recurso de interação de voz - POST /cs/voice-interactions Endpoint para criar um registro de interação de voz na tabela Interaction [interaction].
    2. Em seguida, ligue para Recurso de interação de voz - POST /cs/voice-interactionId/messages Endpoint para armazenar mensagens traduzidas da conversa de voz na tabela Mensagem de conversa. 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. 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 as mensagens de voz, ligue para Recurso de interação de voz - PATCH /cs/voice-interactionId/state endpoint para encerrar a captura e fechar o registro de interação de voz.

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

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

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

    Formato de URL

    URL com controle de versão: /api/now/

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

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 acessado. 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. Passado de volta por Recurso de interação de voz - POST /cs/voice-interactions endpoint.

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    RegistradingURL 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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da 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 mal formado ou parâmetros obrigatórios não foram 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 em ServiceNow instância, a instância registra 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 Interaction [interaction].

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

    Formato de URL

    URL com controle de versão: /api/now/

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

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 acessado. 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(a)
    Tabela 9. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    agentId Identificador exclusivo do agente ao qual atribuir a interação de voz.

    Tipo de dados: Cadeia de caracteres

    Padrão: Invocar Virtual Agent
    CallerPhoneNumber 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.

    Tipo de dados: Cadeia de caracteres

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    ClientSessionId 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).

    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, em conformidade 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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da 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 mal formado ou parâmetros obrigatórios não foram 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 [interaction]

    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-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ão: /api/now/

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

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 acessado. 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 Recurso de interação de voz - POST /cs/voice-interactions Endpoint e armazenados na tabela Interação [interaction].

    Tipo de dados: Cadeia de caracteres
    Tabela 14. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 15. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    agentId Identificador exclusivo do agente ao qual atribuir a interação de voz.

    Tipo de dados: Cadeia de caracteres

    Padrão: Invocar Virtual Agent
    CallerPhoneNumber 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.

    Tipo de dados: Cadeia de caracteres

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    ClientSessionId 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).

    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, em conformidade 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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da 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 mal formado ou parâmetros obrigatórios não foram 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-interactionId/messages

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

    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.

    Formato de URL

    URL com controle de versão: /api/now/

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

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 acessado. 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 adicionar as mensagens especificadas. Este valor é retornado pelo Recurso de interação de voz - POST /cs/voice-interactions Endpoint e armazenados na tabela Interação [interaction].

    Tipo de dados: Cadeia de caracteres
    Tabela 20. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 21. Solicitar parâmetros do corpo (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"
  }
]
    atributos.<json_string>
    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.

    Tipo de dados: Matriz de objetos

    Padrão: Nenhum
    <json_string>.beginOffsetMillis 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.

    Tipo de dados: Longo

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

    Tipo de dados: Cadeia de caracteres
    OffsetMillis.endOffsetMillis <json_string> Obrigatório. Deslocamento 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 ID da mensagem de origem.

    Tipo de dados: Cadeia de caracteres

    Padrão: Nenhum
    EEvento.éEvento <json_string>
    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
    Mensagem.IsInternalInternal <json_string>
    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.

    Tipo de dados: Booliano

    Padrão: falso
    Pontuaçãode alto-falante <json_string>
    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.

    Tipo de dados: Número

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

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

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

    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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da 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 mal formado ou parâmetros obrigatórios não foram 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_transcrit]

    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/transcription

    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 um chamador.

    Formato de URL

    URL com controle de versão: /api/now/

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

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de 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 acessado. 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(a)
    Tabela 27. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    ConversaçãoIniciada Hora de início da conversa.

    Tipo de dados: Cadeia de caracteres

    FORMATO: AAAA-MM-DD HH:MM:SS

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

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]
    origem Nome do canal que criou originalmente a transcrição de interação da conversa.

    Atualmente, o único valor compatível é 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
    atributos.transcrição
    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.

    Tipo de dados: Matriz de objetos

    Padrão: Nenhum
    transcript.beginOffsetMillis 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.

    Tipo de dados: Longo

    Unidade: Milissegundos
    transcription.content Obrigatório. Texto da mensagem a ser adicionado à interação de voz.

    Tipo de dados: Cadeia de caracteres
    Transcription.endOffsetMillis Obrigatório. Deslocamento 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 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
    Transcription.isInternalMessage
    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.

    Tipo de dados: Booliano

    Padrão: falso
    Transcription.loudnessScore
    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.

    Tipo de dados: Número

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

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

    Tipo de dados: Cadeia de caracteres
    transcript.sentiment
    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

    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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da 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 mal formado ou parâmetros obrigatórios não foram 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"  
}