Referencia de los Webhooks de la Voice API

Vonage utiliza webhooks junto con su Voice API para que tu aplicación pueda interactuar con la llamada. Hay dos puntos de conexión de webhooks obligatorios y uno opcional:

• Respuesta webhook se envía cuando se contesta una llamada. Esto es tanto para llamadas entrantes como salientes.
• Webhook de eventos Se envía para todos los eventos que se producen durante una llamada. Tu aplicación puede registrar, reaccionar o ignorar cada tipo de evento.
• URL alternativa Se utiliza cuando el webhook «Answer» o «Event» falla o devuelve un estado de error HTTP.
• Errores también se envían al punto final del webhook del evento si se producen.

Para más información general, consulte nuestro Guía sobre webhooks.

Webhooks firmados

Los webhooks firmados son una forma de verificar que la solicitud proviene de Vonage y que su carga útil no ha sido alterada durante el tránsito. Voice API, al igual que Mensajes y Despacho admiten retrollamadas firmadas por defecto. Véase Descodificación de webhooks firmados para aprender a descifrar la firma de un JWT recibido.

Webhook de respuesta

Cuando se responde a una llamada entrante, se envía una solicitud HTTP a la aplicación answer_url que has especificado al configurar la aplicación. Para las llamadas salientes, especifica el answer_url cuando llames.

Por defecto, el webhook de respuesta será un GET pero se puede sustituir por POST estableciendo el answer_method campo. En el caso de las llamadas entrantes, estos valores se configuran al crear la aplicación. En el caso de las llamadas salientes, estos valores se especifican al realizar una llamada.

Responder a los campos de datos del webhook

Transmisión de datos adicionales con cabeceras SIP

Además de los campos anteriores, puede especificar cualquier encabezado adicional que necesite al utilizar SIP Connect. Todas las cabeceras deben empezar por X- y se enviará a su answer_url con el prefijo SipHeader_. Por ejemplo, si añades un encabezado de X-UserId con un valor de 1938ND9, Vonage añadirá SipHeader_X-UserId=1938ND9 a la solicitud realizada a su answer_url.

Vonage admite X- y las cabeceras De usuario a usuario cabecera. Estos mecanismos pueden utilizarse individualmente o juntos dentro de la misma llamada.

La cabecera Usuario-a-Usuario le permite enviar datos contextuales durante una llamada desde su equipo SIP a su aplicación Voice API. Para utilizar este encabezado, su equipo SIP debe enviar un encabezado Usuario-a-Usuario a su dominio SIP Programable. Además, su aplicación Voice API necesitará recibir el webhook de respuesta que contiene el contenido de esta cabecera.

El Cabecera de usuario a usuario debe tener el siguiente formato: SipHeader_User-to-User=1234567890abcdef;encoding=hex

Ejemplos de campos de datos de los webhooks de respuesta

Para un GET En la solicitud, las variables aparecerán en la URL, de esta forma:

/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9

Si configuras el answer_method a POST entonces recibirá la petición con datos en formato JSON en el cuerpo:

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "SipHeader_X-UserId": "1938ND9"
}

Respuesta al webhook de respuesta

Vonage espera que devuelvas un OCN en formato JSON que contiene las acciones a realizar.

Webhook de eventos

Las solicitudes HTTP del webhook de eventos llegarán al punto final del webhook de eventos cuando se produzca cualquier cambio de estado en una llamada. La URL será la event_url que especificó al crear su aplicación, a menos que lo anule estableciendo un event_url al iniciar una llamada.

Por defecto, las solicitudes entrantes son POST solicitudes con un cuerpo JSON. Puedes sobrescribir el método para GET configurando el event_method además del event_url. Se espera que tu sistema responda a la solicitud HTTP. Si su sistema no confirma el evento o, por el contrario, responde con un código 429, 502, 503 o 504, se intentará volver a realizar la solicitud. Para los eventos que requieran la devolución de un NCCO, se utilizará entonces la URL de reserva. Consulte el URL alternativa Consulte esta sección para obtener más información.

El formato de los datos incluidos depende del suceso que se haya producido:

• started
• ringing
• answered
• busy
• cancelled
• unanswered
• disconnected
• rejected
• failed
• human/machine
• timeout
• completed
• record
• input
• transfer

Comenzó

Indica que se ha creado la convocatoria.

Volver a la lista de webhooks de eventos

Timbre

El destino de la llamada está sonando.

Volver a la lista de webhooks de eventos

Respondido

Se respondió a la llamada.

Volver a la lista de webhooks de eventos

Ocupado

El destinatario está en línea con otra persona que llama.

Volver a la lista de webhooks de eventos

Cancelado

Una llamada saliente es cancelada por el emisor antes de ser contestada.

Volver a la lista de webhooks de eventos

Sin respuesta

O bien no se puede contactar con el destinatario, o bien este ha rechazado la llamada.

Volver a la lista de webhooks de eventos

Desconectado

Si la conexión WebSocket finaliza desde el lado de la aplicación por cualquier motivo, se enviará la llamada de retorno de evento desconectado, si la respuesta contiene una NCCO, se procesará, si no hay NCCO, continuará la ejecución normal.

Volver a la lista de webhooks de eventos

Rechazado

Vonage rechazó la llamada antes de que se conectara.

Volver a la lista de webhooks de eventos

Fallido

No se ha podido establecer la llamada saliente.

Volver a la lista de webhooks de eventos

Persona / Máquina

En el caso de una llamada saliente realizada mediante programación, si el machine_detection un evento con el estado human o machine Se enviará en función de si la persona ha contestado la llamada o no.

Volver a la lista de webhooks de eventos

Tiempo de espera

Si la duración de la fase de timbre supera el valor especificado ringing_timeout durante ese tiempo, se enviará este evento.

Volver a la lista de webhooks de eventos

Completado

La llamada ha terminado, este evento también incluye datos de resumen sobre la llamada.

Volver a la lista de webhooks de eventos

Registro

Este webhook se activa cuando finaliza una acción «record» de NCCO. Al crear una acción «record», puedes establecer un eventUrl para que este evento sea enviado. Esto puede ser útil si desea utilizar un código separado para manejar este tipo de evento.

Transcripción

Volver a la lista de webhooks de eventos

Entrada

Vonage envía este webhook cuando finaliza una OCNC con una acción de "entrada".

Resultados de la captura DTMF

Resultados del reconocimiento de voz

Texto transcrito

Véase también el ejemplo completo de carga útil que se muestra en Referencia OCNC

Volver a la lista de webhooks de eventos

Transferencia

Este webhook es enviado por Vonage cuando un tramo ha sido transferido de una conversación a otra. Esto se puede hacer usando un NCCO o la función transfer acción

Volver a la lista de webhooks de eventos

URL alternativa

Se accede al webhook de reserva cuando el webhook de respuesta o el webhook de evento —en los casos en que se espera que el evento responda con un NCCO— devuelve un estado de error HTTP o no está accesible. Los datos que se devuelven desde la URL de reserva son los mismos que se recibirían en la URL de respuesta original o en la URL de evento, con la incorporación de dos nuevos parámetros: reason y original_request:

{
  "reason": "Connection closed.",
  "original_request": {
    "url": "https://api.example.com/webhooks/event",
    "type": "event"
  }
}

Si hubo una conexión cerrada o restablecida, un tiempo de espera o un código de estado HTTP de 429, 503 o 504 durante la OCN inicial el answer_url Si se intenta dos veces, entonces:

1. Intenta ponerte en contacto con el fallback_answer_url dos veces
2. Si no hay éxito, se termina la llamada

Si hubo una conexión cerrada o restablecida, un tiempo de espera o un código de estado HTTP de 429, 503 o 504 Durante una llamada en curso, el event_url para eventos que se espera que devuelvan un NCCO (por ejemplo, el resultado de un input o notify acción) se intenta dos veces, entonces:

1. Intenta ponerte en contacto con el fallback_answer_url dos veces
2. Si no se consigue, continuar con el flujo de la llamada

Errores

El punto final de eventos también recibirá webhooks en caso de error. Esto puede ser útil a la hora de depurar tu aplicación.