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 - Ofrece una detección más precisa y total flexibilidad para configurar cualquier flujo de llamadas. Además, incluye detección de pitidos y un modo de funcionamiento asíncrono que permite un mejor control de las llamadas. La detección automática avanzada es una función de pago; las tarifas exactas se pueden consultar en la 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 la llamada y detección de dispositivos
Independientemente del tipo de detección de dispositivo (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 dicha solicitud incluye la activación de la detección de máquinas, el proceso de establecimiento de la llamada 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
- Respondido
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 del evento en el 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
- Eventos relacionados con personas o máquinas (incluido el pitido, cuando proceda)
- Procesar la primera instrucción NCCO
- (Opcional) eventos relacionados con la instrucción de la OCNC (cuando proceda)
- Más instrucciones de la NCCO
Identificar si la otra parte es una máquina o una persona tarda entre 4 y 5 segundos, por lo que el lado de Vonage 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 comienza tras el evento de respuesta, mientras se lleva a cabo la detección automática 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, una vez finalizada la primera acción, Vonage seguirá procesando las acciones posteriores del NCCO mientras se lleva a cabo 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 De lo contrario. En ambos casos, la aplicación recibirá notificaciones con los resultados de la detección, para que sepas si la persona ha contestado la llamada o no.
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 señalar que la detección estándar de máquinas se realiza de forma sincrónica, lo que significa, una vez más, que la detección se lleva a cabo antes de recuperar y procesar la primera acción NCCO. Mientras se lleva a cabo 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 automática avanzada de Vonage se ha diseñado para mejorar tanto la precisión de la detección como la experiencia de voz que Vonage es capaz de ofrecer.
Nota: Se trata de una función premium, con un coste adicional de 0,0070 € por llamada cuando la Detección Automática Avanzada está activada.
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 el 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 activa el contestador automático, continúa con la llamada.hangup- Si se detecta un contestador automático, finaliza 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 dehangupfrente acontinueal gestionar las llamadas, también es posible definir uno de los tres modos. A continuación se describen con más detalle.
default Modo
El default Este modo ofrece el máximo nivel de control sobre la llamada. Funciona de forma asíncrona, 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 cualquiera de los siguientes: 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 un nuevo NCCO que sustituirá al 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 máquina con sub_state beep_start indica el inicio 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 De acuerdo con el nuevo NCCO, con el mensaje que debe incluirse 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 En este modo, es posible crear experiencias de voz en las que no haya silencios al inicio de la llamada, con la posibilidad de dejar mensajes de buzón de voz justo después del pitido, evitando así que el mensaje quede truncado.
detect Modo
El detect Este modo tiene el mismo comportamiento que la «Detección automática estándar», pero ofrece una identificación más precisa de los dispositivos. Permite a los desarrolladores que deseen migrar su antigua aplicación de voz, basada en la «Detección automática estándar», hacerlo con cambios mínimos en el código.
Por lo general, este modo debe utilizarse cuando se desea colgar la llamada al detectar que hay una máquina al otro lado. Es síncrono, por lo que si continue se utiliza en lugar de hangup esperará hasta que se haya detectado la presencia de una persona o una máquina para empezar a procesar el NCCO a partir 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
El 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 se desea ese comportamiento. Si human si se detecta, 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 de este modo es que, cuando se detecta una máquina, Vonage esperará a que el beep evento (o beep_timeout) antes de procesar el NCCO o la siguiente acción del NCCO. Esto permite, en la práctica, que Vonage envíe un mensaje a una persona o lo deje en el buzón de voz tras un pitido.