Detecção de correio de voz (detecção automática de máquina)

Ao usar a Voice API da Vonage para criar uma experiência de chamada de saída, às vezes é necessário levar em conta quem — ou, em alguns casos, o que — está atendendo a chamada. Talvez a experiência que precise ser criada seja destinada apenas a pessoas; nesse caso, a chamada deve ser encerrada quando atendida por um sistema de correio de voz. Ou, caso um sistema de correio de voz atenda a chamada, pode ser necessário deixar uma mensagem personalizada após o bipe.

A Vonage oferece dois recursos diferentes para casos de uso de detecção automática:

Detecção Padrão de Máquinas - oferece recursos básicos de detecção automática, com opções para encerrar a chamada automaticamente ou apenas informar ao aplicativo que a chamada provavelmente foi atendida pela caixa postal. Sem cobranças adicionais.
Detecção Avançada por Máquina - oferece detecção mais precisa e total flexibilidade para criar qualquer fluxo de chamadas. Além disso, oferece detecção de bipe e um modo de funcionamento assíncrono que permite um melhor controle das chamadas. A Detecção Automática Avançada é um recurso cobrado; as tarifas exatas podem ser consultadas no Preços da Voice API página na seção “Recursos programáveis”.

Observação: Se você tentar usar os dois métodos na mesma chamada, a Detecção Avançada de Máquinas terá prioridade e a opção padrão não será utilizada.

Estabelecimento de chamada e detecção de aparelho

Independentemente do tipo de detecção de aparelho (padrão ou avançada) utilizado, os mesmos princípios se aplicam. Quando a Voice API da Vonage recebe a instrução para fazer uma chamada para um número de telefone, seja por meio de uma solicitação POST ou de uma ação de conexão NCCO, e essa solicitação inclui a ativação da detecção de máquina, o processo de estabelecimento da chamada passa pelos mesmos estágios descritos em Fluxo de chamadas.

Uma chamada bem-sucedida sempre passará pelos seguintes estágios antes de qualquer detecção de aparelho:

Iniciado
Zumbido
Respondido

Assim que a chamada atingir o estado “atendida”, a detecção de máquina é iniciada. Para que a detecção de máquina tenha início, é necessário que a chamada esteja estabelecida e que o áudio comece a ser transmitido para a Vonage. É com base na análise desse áudio que a Vonage determina se foi uma pessoa ou uma máquina que atendeu a chamada.

A Vonage sempre enviará os resultados para o webhook do evento no status campo de um Webhook do tipo “Humano/Máquina”.

Com isso em mente, vamos discutir a sequência de eventos envolvidos na detecção e no processamento de chamadas, antes de nos aprofundarmos em como usar cada tipo de detecção automática.

Implementações síncronas e assíncronas

No que diz respeito ao processamento de chamadas e às ações do NCCO, há duas opções de implementação: síncrona e assíncrona.

No modo síncrono, todas as atividades relacionadas à detecção da máquina são realizadas, e somente após a conclusão dessas atividades a Vonage começa a processar as instruções do NCCO.

Isso significa que, após o atendimento de uma chamada, ocorre o seguinte, em ordem sequencial:

Evento respondido
Evento(s) humano/máquina (incluindo sinal sonoro, quando aplicável)
Processar a primeira instrução do NCCO
(Opcional) eventos relacionados ao ensino do NCCO (quando aplicável)
Outras instruções da NCCO

A identificação da outra parte da chamada como máquina ou pessoa leva de 4 a 5 segundos; por isso, o lado da Vonage fica em silêncio até que a identificação seja concluída.

Quando não é realizada a detecção de máquina, após o atendimento da chamada, o NCCO é buscado e imediatamente começa a ser processado. Isso significa que, nos casos em que uma pessoa atende a chamada, não há silêncio no início da chamada, proporcionando uma experiência aprimorada para o usuário final. Para preencher a lacuna entre a ausência de detecção automática e a detecção automática, a Vonage desenvolveu o modo assíncrono na nova oferta avançada de detecção automática.

No modo assíncrono, as etapas de detecção do aparelho ocorrem paralelamente ao processamento do NCCO. Assim, após a chamada ser atendida, é assim que as Applications podem esperar que os eventos cheguem e sejam processados:

Nesse caso, a primeira ação do NCCO é iniciada após o evento de resposta, enquanto a detecção automática é realizada em segundo plano. Se essa ação for do tipo “falar”, isso significa que não haverá silêncio no canal enquanto a detecção estiver ocorrendo. Além disso, se a primeira ação for concluída, a Vonage continuará processando as ações subsequentes do NCCO enquanto a detecção estiver ocorrendo.

Detecção Padrão de Máquinas

Quando a detecção padrão de atendimento automático está ativada, uma aplicação pode saber se a chamada foi atendida por uma caixa postal/atendimento automático ou por uma pessoa. Os desenvolvedores devem definir um dos dois comportamentos a serem adotados quando for detectado um atendimento automático: continue ou hangup.

Por exemplo, você pode querer criar uma chamada com detecção de máquina que desligue caso uma máquina atenda, ou que obtenha um NCCO do answer_url caso contrário. Em ambas as situações, o aplicativo receberá eventos com os resultados da detecção, para que você saiba se a pessoa atendeu a chamada ou não.

Para fazer isso, você enviaria uma solicitação POST para https://api.nexmo.com/v1/calls/, utilizando um JWT como método de autorização.

O corpo da solicitação deve conter algo como isto:

{
   "answer_url": [
      "https://example.com/answer"
   ],
   "answer_method": "POST",
   "to": [
      {
         "type": "phone",
         "number": "14155550100",
      }
   ],
   "from": {
      "type": "phone",
      "number": "14155550100"
   },
   "event_url": [
      "https://example.com/event"
   ],
   "event_method": "POST",
   "machine_detection": "hangup"
}

Se, em vez de hangup, continue se fosse usado, o NCCO seria buscado, mas seu aplicativo também receberia o evento de resultado por meio de um Retorno de chamada entre pessoa e máquina à URL do seu evento.

É importante observar que a detecção padrão de máquinas ocorre de forma síncrona, o que significa, mais uma vez, que a detecção é realizada antes da obtenção e do processamento da primeira ação NCCO. Enquanto a detecção está ocorrendo, é impossível interagir com o usuário que está recebendo a chamada.

Para ver mais exemplos de como fazer uma chamada usando a Voice API, consulte este trecho de código.

A detecção automática também está disponível a partir de um Ação NCCO Connect, com as mesmas opções de hangup e continue:

{
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "machineDetection": "hangup",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }

Detecção Avançada por Máquina

O recurso de Detecção Automática Avançada da Vonage foi desenvolvido para melhorar tanto a precisão da detecção quanto a experiência de voz que a Vonage é capaz de oferecer.

Observação: este é um recurso premium, com um custo adicional de €0,0070 por chamada em que a Detecção Avançada de Máquinas estiver ativada.

Para usar a detecção automática avançada ao fazer uma nova chamada, você deve enviar uma solicitação POST para https://api.nexmo.com/v1/calls/, utilizando um JWT como método de autorização.

O corpo da solicitação deve conter o advanced_machine_detection configuração:

{
   "answer_url": [
      "https://example.com/answer"
   ],
   "answer_method": "POST",
   "to": [
      {
         "type": "phone",
         "number": "14155550100",
      }
   ],
   "from": {
      "type": "phone",
      "number": "14155550100"
   },
   "event_url": [
      "https://example.com/event"
   ],
   "event_method": "POST",
   "advanced_machine_detection": {
       "behavior" : “continue”,
       "mode": “default”,
       "beep_timeout": 45
   }
}

Isso também pode ser feito usando um Ação NCCO Connect, com as mesmas opções de hangup e continue:

{
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "advancedMachineDetection": {
        "behavior" : “continue”,
        "mode": “default”,
        "beep_timeout": 45
    }
    "endpoint": [
        {
        "type": "phone",
        "number": "447700900001"
        }
    ]
}

Como pode ser visto nos exemplos, advanced_machine_detection (ou advancedMachineDetection) possui três parâmetros configuráveis:

behavior - isso define o que a plataforma da Vonage deve fazer ao detectar uma resposta automática. Os valores possíveis são:
- continue - Se houver uma resposta automática, continue com a ligação.
- hangup - Se houver um tom de linha, encerre a ligação.
beep_timeout- isso permite que você defina por quanto tempo esperar pelo bipe da caixa postal e, caso ele não seja recebido, gerar um evento de webhook correspondente.
mode - além do comportamento principal de hangup versus continue Ao lidar com chamadas, também é possível definir um dos três modos. Eles são abordados com mais detalhes a seguir.

`default` Modo

O default Esse modo oferece o mais alto nível de controle sobre a chamada. Ele funciona de forma assíncrona, o que significa que a Vonage começa a processar as ações do NCCO já durante a fase de detecção.

A título de exemplo, suponha que esse NCCO tenha sido devolvido à Vonage em resposta à solicitação de obtenção do NCCO a partir do answer_url:

[
  {
    "action": "talk",
    "text": "Hello from Vonage Voice API. We would like to inform you of a very important message",
    "language": "en-GB",
    "loop": 3
  }
]

Assim que a chamada for atendida, essa mensagem começará a ser reproduzida imediatamente e será repetida três vezes, enquanto os algoritmos de detecção automática processam o áudio do interlocutor em paralelo.

Durante essa ação de comunicação, pode ocorrer um resultado de detecção automática; nesse caso, um webhook é enviado para o event_url.

O webhook terá a seguinte aparência (com human ou machine (como status):

{
  "from": "442079460000",
  "to": "447700900000",
  "status": "human/machine",
  "call_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  }

Independentemente de o evento enviado ao aplicativo ser gerado por um usuário ou por uma máquina, o aplicativo pode responder a esse webhook de duas maneiras. Ou retornar um 204 para continuar ou retornar um 200 com um novo NCCO que substituirá o NCCO anterior.

Isso significa que uma aplicação pode diferenciar o comportamento. Se for um ser humano, a chamada poderia continuar com o mesmo NCCO e realizar outras ações, como solicitar e processar entradas DTMF.

Se for uma máquina, o aplicativo poderia aguardar o bipe e, em seguida, deixar uma mensagem de voz personalizada. A evento de máquina com sub_state beep_start indica o início do bipe da mensagem de voz. Por outro lado, beep_timeout sub_state indica que o bipe não foi recebido após a espera pelo período designado. O aplicativo também pode retornar um 200 Tudo certo com o novo NCCO, com a mensagem que deve ser gravada na caixa postal.

O trecho de código a seguir, executado em uma aplicação, utilizaria uma nova ação de voz caso fosse detectada uma máquina, indicando que a plataforma deve aguardar o bipe (para fins ilustrativos; em um exemplo real, um 204 poderia ser usado em vez disso), enquanto que se sub_state é beep_start ela grava a mensagem de correio de voz propriamente dita após o bipe.

app.post('/onEvent', (req, res, next) => {
  try {
…
    if(req.body.status == 'machine' && !(req.body.sub_state == 'beep_start') ) {
      const ncco = [{
        action: 'talk',
        text: 'Oh, it\'s actually a machine. Let’s wait for beep'
      }];
      console.log(req.body);
      res.json(ncco);
    }
    else if(req.body.status == 'machine' && req.body.sub_state == 'beep_start' ) {
      const ncco = [{
        action: 'talk',
        text: 'This is a very important message Vonage will leave in the voicemail after the beep'
      }];
      console.log(req.body);
      res.json(ncco);
    }
    else {
      console.log(req.body);
      res.send(204);
    }

Com default Nesse modo, é possível criar experiências de voz nas quais não há silêncios no início da chamada, com a possibilidade de deixar mensagens na caixa postal logo após o bipe, evitando que a mensagem seja cortada.

`detect` Modo

O detect Esse modo apresenta o mesmo comportamento que a Detecção Padrão de Máquinas, mas com uma identificação mais precisa das máquinas. Ele permite que os desenvolvedores que desejam migrar seus aplicativos de voz antigos, criados com base na Detecção Padrão de Máquinas, façam isso com alterações mínimas no código.

Normalmente, esse modo deve ser usado quando o comportamento desejado é desligar a chamada na presença de uma máquina. Ele é síncrono; portanto, se continue é usado no lugar de hangup ele aguardará até que seja detectada a presença de um ser humano ou de uma máquina para começar a processar o NCCO a partir do answer_url se for uma nova chamada criada por meio de POST, ou a próxima ação em um NCCO após uma ação de conexão com detecção.

`detect_beep` Modo

O detect_beep esse modo se baseia no detect modo que permite que uma mensagem de correio de voz seja gravada logo após o bipe. Esse modo deve ser usado quando um continue esse comportamento é desejado. Se human se for detectado, ele se comporta exatamente como detect modo, no sentido de que ele é executado de forma síncrona, aguardando a conclusão da detecção da máquina antes de processar o NCCO ou a próxima ação do NCCO.

A principal diferença nesse modo é que, quando um aparelho é detectado, a Vonage aguarda até que o beep evento (ou beep_timeout) antes de processar o NCCO ou a próxima ação do NCCO. Isso permite, na prática, que a Vonage entregue uma mensagem a uma pessoa ou a deixe na caixa postal após um bipe.