Referencia de los Webhooks de la Voice API

Vonage utiliza webhooks junto con su Voice API para permitir que tu aplicación interactúe con la llamada. Hay dos puntos finales de webhook obligatorios y uno opcional:

• Respuesta webhook se envía cuando se contesta una llamada. Esto es tanto para llamadas entrantes como salientes.
• Evento webhook 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 de Respuesta o Evento falla o devuelve un estado de error HTTP.
• Errores también se envían al punto final del webhook de eventos si se producen.

Para más información general, consulte nuestro guía de 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 descodificar una firma JWT entrante.

Respuesta Webhook

Cuando se responde a una llamada entrante, se envía una solicitud HTTP a la aplicación answer_url que especificó al configurar la aplicación. Para las llamadas salientes, especifique el answer_url cuando hagas la llamada.

Por defecto, el webhook de respuesta será un GET pero se puede sustituir por POST estableciendo el answer_method campo. Para las llamadas entrantes, estos valores se configuran al crear la aplicación. Para 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ñade una cabecera de X-UserId con un valor de 1938ND9Vonage 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.

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

Ejemplos de campos de datos de webhook de respuesta

Para un GET las variables estarán en la URL, así:

/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 ajusta 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.

Evento webhook

Las solicitudes HTTP de webhook de eventos llegarán al punto final de webhook de eventos cuando se produzca algún 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 con un cuerpo JSON. Puede anular el método para GET configurando el event_method además del event_url. Se espera que su sistema responda a la solicitud HTTP. Si su sistema no acusa recibo del evento o responde con un 429, 502, 503 o 504, se intentará reintentarlo. Para los eventos que requieren que se devuelva una OCN, se utilizará la URL de reserva. Consulte la página URL alternativa para 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

Respuesta

Se respondió a la llamada.

Volver a la lista de webhooks de eventos

Ocupado

El destino 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

El destinatario está ilocalizable o 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 conectar la llamada saliente.

Volver a la lista de webhooks de eventos

Humano / Máquina

Para 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 una persona ha respondido a 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 de ringing_timeout 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 llega cuando una NCCO con una acción "record" ha finalizado. Al crear una acción de registro, puede 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 mostrado 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 fallback cuando el webhook de respuesta o el webhook de evento, cuando se espera que el evento responda con una NCCO, devuelve un estado de error HTTP o es inalcanzable. Los datos que se devuelven desde la URL de retorno son los mismos que se recibirían en la URL de respuesta original o en la URL de evento, con la adició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 se intenta dos veces, entonces:

1. Intento de alcanzar 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, la devolución de un input o notify acción) se intenta dos veces, entonces:

1. Intento de alcanzar el fallback_answer_url dos veces
2. Si no hay éxito, continúa el flujo de llamadas

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.