Detección de buzón de voz (detección automática de máquinas)

Al usar la Voice API de Vonage para crear una experiencia de voz saliente, a veces es necesario tener en cuenta quién, o en algunos casos qué, responde la llamada. Quizás la experiencia que se necesita crear es sólo para humanos, en cuyo caso la llamada debería desconectarse cuando la conteste un sistema de correo de voz. O, en el caso de que un sistema de buzón de voz responda a la llamada, podría ser necesario dejar un mensaje personalizado después de la señal acústica.

Vonage ofrece dos funciones diferentes para casos de uso de detección de máquinas:

Detección de máquinas estándar - proporciona la capacidad básica de detección de máquinas con opciones para cortar la llamada automáticamente o simplemente informar a la aplicación del hecho de que la llamada probablemente fue contestada por el buzón de voz. Sin cargos adicionales.
Detección avanzada de máquinas - proporciona una detección más precisa y una flexibilidad total para construir cualquier flujo de llamadas. También ofrece detección de pitidos y un modo de funcionamiento asíncrono que permite un mejor control de las llamadas. La Detección Avanzada de Máquinas es una función de pago; las tarifas exactas pueden consultarse en la página Precios de Voice API en "Funciones programables".

Nota: Si intenta utilizar ambos métodos en la misma llamada, tendrá prioridad la Detección Avanzada de Máquinas y no se utilizará la opción estándar.

Establecimiento de llamada y detección de máquinas

Independientemente del tipo de detección automática (estándar o avanzada) que se utilice, se aplican los mismos principios. Cuando se indica a la Voice API de Vonage que realice una llamada a un número de teléfono, ya sea mediante una solicitud

POST

o una acción de conexión NCCO, y esa solicitud incluye la activación de la detección de máquinas, el proceso de establecimiento de llamadas pasa por los mismos estados que se describen en. Flujo de llamadas.

Una llamada exitosa siempre pasará por los siguientes estados antes de cualquier detección de la máquina:

Comenzó
Timbre
Respuesta

Una vez que la llamada ha alcanzado el estado de respuesta, comienza la detección de máquina. Para que comience cualquier detección de máquina, necesitamos que se establezca la llamada y que el audio comience a fluir hacia Vonage. Es en base al análisis de este audio que Vonage determina si fue un humano o una máquina quien respondió la llamada.

Vonage siempre enviará los resultados al webhook de eventos del status campo de un Webhook de tipo humano/máquina.

Con esto en mente, vamos a discutir la secuencia de eventos involucrados en la detección y procesamiento de llamadas, antes de sumergirnos en cómo utilizar cada tipo de detección de máquinas.

Implementaciones síncronas y asíncronas

En cuanto al procesamiento de llamadas y acciones NCCO, existen dos opciones de implementación: síncrona y asíncrona.

En el modo síncrono, se realizan todas las actividades relacionadas con la detección de la máquina y, sólo cuando finalizan, Vonage comienza a procesar las instrucciones NCCO.

Esto significa que, una vez contestada una llamada, sucede lo siguiente de forma secuencial:

Evento contestado
Evento(s) humano(s)/máquina(s) (incluido el evento de pitido cuando proceda)
Procesar la primera instrucción NCCO
(Opcional) eventos relacionados con la instrucción de la OCNC (cuando proceda)
Otras instrucciones de la OCNC

Identificar la parte remota como máquina o humano lleva hasta 4-5 segundos, por lo que el lado de Vonage de la llamada permanece en silencio hasta que se completa la identificación.

Cuando no se realiza la detección automática, una vez que se responde a la llamada, se obtiene la NCCO y se empieza a procesar inmediatamente. Esto significa que en los casos en que un humano contesta la llamada, no hay silencio al comienzo de la llamada, lo que brinda una mejor experiencia al usuario final. Para cerrar la brecha entre la no detección de máquinas y la detección de máquinas, Vonage desarrolló el modo asíncrono en la nueva oferta de detección de máquinas avanzada.

En modo asíncrono, los pasos de detección de la máquina ocurren en paralelo con el procesamiento de la OCNC. Por tanto, después de que se responda a la llamada, así es como las Applications pueden esperar que lleguen y se procesen los eventos:

En este caso, la primera acción del NCCO se inicia tras el evento de respuesta, mientras se realiza la detección de la máquina en segundo plano. Si esta acción es una acción de conversación, esto significa que no habrá silencio en el canal mientras se realiza la detección. Además, si la primera acción finaliza, Vonage continuará procesando otras acciones del NCCO mientras se realiza la detección.

Detección de máquinas estándar

Cuando la detección de máquina estándar está activada es posible que una aplicación sepa si un buzón de voz / máquina o un humano respondió a la llamada. Los desarrolladores deben definir uno de los dos comportamientos para cuando se detecta una máquina: continue o hangup.

Por ejemplo, puede que desee crear una llamada con detección de máquina que cuelgue en caso de que una máquina responda, o que obtenga una NCCO del answer_url en caso contrario. En ambas situaciones, la aplicación recibirá eventos con los resultados de la detección para que sepas si la persona respondió o no a la llamada.

Para ello, debe realizar una solicitud

POST

a https://api.nexmo.com/v1/calls/utilizando un JWT como método de autorización.

El cuerpo de la solicitud debe contener algo como esto:

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

Si en lugar de hangup, continue se obtendría la OCNC, pero la aplicación también recibiría el evento de resultado a través de un evento Retorno de llamada humano/máquina a la URL de su evento.

Es importante tener en cuenta que la detección de la máquina estándar se produce de forma sincrónica, lo que significa que la detección se realiza antes de obtener y procesar la primera acción NCCO. Mientras se realiza la detección, es imposible interactuar con el usuario que recibe la llamada.

Para ver más ejemplos de cómo realizar una llamada utilizando la Voice API, consulte este fragmento de código.

La detección automática también está disponible en un NCCO connect actioncon las mismas opciones de hangup y continue:

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

Detección avanzada de máquinas

La función de detección avanzada de máquinas de Vonage se creó para mejorar tanto la precisión de la detección como la experiencia de voz que Vonage puede ofrecer.

Nota: Se trata de una función premium, con un coste adicional de 0,0070 euros por cada llamada en la que se active la Detección Avanzada de Máquinas.

Para utilizar la detección avanzada de máquinas al realizar una nueva llamada, debería realizar una solicitud

POST

a https://api.nexmo.com/v1/calls/utilizando un JWT como método de autorización.

El cuerpo de la solicitud debe contener advanced_machine_detection configuración:

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

Esto también puede hacerse utilizando un NCCO connect actioncon las mismas opciones de hangup y 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 se ve en los ejemplos, advanced_machine_detection (o advancedMachineDetection) tiene tres parámetros configurables:

behavior - define qué debe hacer la plataforma de Vonage cuando se encuentra con una máquina. Los valores posibles son:
- continue - Si se encuentra la máquina, continúe con la llamada.
- hangup - Si se encuentra la máquina, finalice la llamada.
beep_timeout- esto le permite definir cuánto tiempo debe esperar el pitido del buzón de voz, y en el caso de que no se reciba, generar un evento webhook correspondiente.
mode - además del comportamiento principal de hangup frente a continue al gestionar las llamadas, también es posible definir uno de los tres modos. A continuación se describen con más detalle.

`default` Modo

En default brinda el nivel más alto de control a la llamada. Este modo funciona de manera asincrónica, lo que significa que Vonage comienza a procesar las acciones de NCCO durante la fase de detección.

A modo de ejemplo, supongamos que esta NCCO se devolvió a Vonage en respuesta a la obtención de NCCO de la aplicación 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
  }
]

Una vez contestada la llamada, este mensaje comenzará a reproducirse inmediatamente y se repetirá tres veces mientras los algoritmos de detección de máquinas procesan en paralelo el audio de la parte remota.

Durante esta acción de conversación, puede producirse un resultado de detección de máquina, en cuyo caso se envía un webhook al event_url.

El webhook tendrá este aspecto (con human o machine como estado):

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

Independientemente de que se envíe un evento humano o de máquina a la aplicación, ésta puede responder a dicho webhook de dos maneras. O bien devuelve un 204 para continuar, o devuelve un 200 con una nueva OCN que sustituirá a la anterior.

Esto significa que una aplicación puede diferenciar comportamientos. Si es humana, la llamada podría continuar con la misma OCN y completar otras acciones, como solicitar y procesar la entrada DTMF.

Si se trata de un contestador automático, la aplicación podría esperar a que suene la señal y dejar un mensaje de voz personalizado. A evento de la máquina con sub_state beep_start indica el comienzo del pitido del buzón de voz. Por el contrario, beep_timeout sub_state indica que no se ha recibido el pitido tras esperar el periodo designado. La aplicación también puede devolver un 200 OK con un nuevo NCCO, con el mensaje que debe colocarse en el buzón de voz.

El siguiente fragmento de código que se ejecuta en una aplicación utilizaría una nueva acción de conversación en caso de que se detectara una máquina, indicando que la plataforma debe esperar el pitido (a efectos ilustrativos, en un ejemplo real un 204 en su lugar), mientras que si sub_state es beep_start deja el mensaje de voz real después del pitido.

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);
    }

Con default es posible crear experiencias de voz en las que no haya silencios al principio de la llamada, con la posibilidad de dejar mensajes de voz justo después de la señal acústica, evitando que el mensaje quede truncado.

`detect` Modo

En detect tiene el mismo comportamiento que la Detección de Máquinas Estándar con una identificación más precisa de las máquinas. Permite a los desarrolladores que quieran migrar su antigua aplicación de voz, creada sobre Detección de Máquinas Estándar, hacerlo con cambios mínimos en el código.

Normalmente, este modo debe utilizarse cuando el comportamiento deseado es colgar la llamada en presencia de una máquina. Es síncrono, por lo que si continue en lugar de hangup esperará hasta después de la detección de un humano o una máquina para empezar a procesar la OCN del answer_url si se trata de una nueva llamada creada a partir de

POST

, o de la siguiente acción en una OCN después de una acción de conexión con detección.

`detect_beep` Modo

En detect_beep se basa en el modo detect permitiendo depositar un mensaje de voz justo después de la señal acústica. Este modo se debe utilizar cuando un continue comportamiento deseado. Si human se comporta exactamente igual que detect en el sentido de que se ejecuta de forma sincrónica y espera a que finalice la detección de la máquina antes de procesar la NCCO o la siguiente acción NCCO.

La principal diferencia en este modo es que cuando se detecta una máquina, Vonage esperará a que el beep evento (o beep_timeout) antes de procesar la acción NCCO o NCCO siguiente. Esto efectivamente permite que Vonage entregue un mensaje a un humano o lo deje en un mensaje de voz después de un pitido.

Detección de buzón de voz (detección automática de máquinas)

Establecimiento de llamada y detección de máquinas

Implementaciones síncronas y asíncronas

Detección de máquinas estándar

Detección avanzada de máquinas

default Modo

detect Modo

detect_beep Modo

`default` Modo

`detect` Modo

`detect_beep` Modo