Detalles técnicos

NOTA: En esta sección de la documentación se describe Applications V2 funcionalidad.

Una aplicación de la API de Vonage contiene la información de seguridad y configuración necesaria para conectarse a los terminales de Vonage y utilizar las API de Vonage.

Cada aplicación de Vonage que se cree puede admitir múltiples funciones; por ejemplo, puedes crear una aplicación que admita el uso de las Voice API, Messages API y RTC.

Para ilustrar el uso de las aplicaciones de Vonage, aquí se presenta un breve resumen para crear y utilizar una aplicación de voz de Vonage:

Crea una aplicación de Vonage mediante la CLI, el panel de control o la API de aplicaciones.
Asegúrate de configurar las URL de tus webhooks. Vonage enviará información importante a estas URL.
Asocia un número de Vonage con tu aplicación de Vonage.
Escribe tu aplicación web. Implementa los puntos finales de webhook que configuraste en el paso 2, usando las API de Vonage según sea necesario.

Por ejemplo, si quieres crear una aplicación que desvía las llamadas entrantes a un teléfono de destino, deberá realizar los siguientes pasos:

Crea una aplicación de Vonage que tenga funciones de voz.
Se configuran las URL de los webhooks de respuesta y evento.
Debes asociar un número de Vonage a tu aplicación de Vonage.
Implemente una aplicación web que responda a las devoluciones de llamada de las URL de los webhooks.
Cuando se realiza una llamada entrante al número de Vonage asociado con la aplicación de Vonage, un OCN se devuelve en el answer_url.

Otros tipos de aplicaciones, como las que cuentan con funciones de mensajes y despacho, siguen un proceso ligeramente diferente, que se describe en las secciones correspondientes de este documentación.

Las siguientes secciones explican las aplicaciones de Vonage con más detalle.

Estructura

Cada aplicación incluye lo siguiente:

Nombre	Descripción
`id`	Se utiliza para identificar cada aplicación y se emplea junto con `private_key` para generar JWT.
`name`	El nombre de la aplicación.
`capabilities`	Describe los tipos de funcionalidades que admitirá esta aplicación. Las capacidades `voice`, `messages`, `rtc`, `vbc`. Una aplicación puede admitir cualquier número de estas funciones. También puede establecer `webhooks` para cada capacidad especificada. Vonage envía y recupera información a través de los puntos finales de webhook.
`keys`	Contiene `private_key` y `public_key`. La clave privada se utiliza para generar los JWT que sirven para autenticar tus llamadas a las API de Vonage. Vonage utiliza la clave pública para autenticar el JWT en tus solicitudes a la API de Vonage.

Capacidades

Una aplicación de Vonage puede usar varias API, como Voice, Messages and Dispatch, Conversation y Client SDK.

Al crear una aplicación, puedes especificar las funcionalidades que deseas que admita. Para cada funcionalidad, puedes configurar webhooks en función de las que necesites; por ejemplo, para una aplicación con una rtc función, podrías especificar una URL de eventos para recibir eventos RTC. Si tu aplicación también necesitara utilizar voice también podría establecer una URL de respuesta para recibir un webhook de respuesta de llamada, una URL de reserva en caso de que su URL de respuesta falle, y otra URL de evento para recibir eventos relacionados con llamadas de voz.

En la siguiente tabla se ofrece un resumen de las prestaciones:

Capacidad	Descripción
`voice`	Se utiliza para las funciones de voz.
`messages`	Se utiliza para dar soporte a las funciones de Messages y Dispatch API.
`rtc`	Se utiliza para admitir las funciones de WebRTC. Normalmente se utiliza con el Client SDK.
`vbc`	Se utiliza para determinar los precios, pero actualmente no tiene otras funciones.

Webhooks

Las URL de webhooks que se proporcionan al crear una aplicación dependen de las capacidades de la aplicación requeridas. La siguiente tabla resume los webhooks:

Capacidad	API utilizada	Webhooks disponibles
`voice`	Voz	`answer_url`, `fallback_answer_url`, `event_url`
`messages`	Mensajes y envío	`inbound_url`, `status_url`
`rtc`	Client SDK	`event_url`
`vbc`	VBC	Ninguno

Tipos de webhook

La siguiente tabla describe los webhooks disponibles por capacidad:

Capacidad	Gancho web	API	Ejemplo	Descripción
`voice`	`answer_url`	Voz	https://example.com/webhooks/answer	La URL a la que Vonage realiza una solicitud cuando se realiza/recibe una llamada. Debe devolver una NCCO.
`voice`	`fallback_answer_url`	Voz	https://example.com/webhooks/fallback	Si el `fallback_answer_url` una vez configurado, Vonage le envía una solicitud si el `answer_url` está desconectado o devuelve un código de error HTTP, o bien el `event_url` está fuera de línea o devuelve un código de error y se espera que un evento devuelva una NCCO. La dirección `fallback_answer_url` debe devolver un NCCO. Si tu `fallback_answer_url` Si falla tras dos intentos de realizar una NCCO inicial, la llamada se da por terminada. Si tu `fallback_answer_url` falla después de dos intentos para una llamada en curso, el flujo de llamada continúa.
`voice`	`event_url`	Voz	https://example.com/webhooks/event	Vonage enviará eventos de llamada (por ejemplo, timbre, llamada contestada) a esta URL.
`messages`	`inbound_url`	Mensajes, Despacho	https://example.com/webhooks/inbound	Vonage reenviará los mensajes entrantes a esta URL.
`messages`	`status_url`	Mensajes, Despacho	https://example.com/webhooks/status	Vonage enviará actualizaciones del estado de los mensajes (por ejemplo, `delivered`, `seen`) a esta URL.
`rtc`	`event_url`	Client SDK, Conversación	https://example.com/webhooks/rtcevent	Vonage enviará eventos RTC a esta URL.
`vbc`	Ninguno	Terminal de voz	Ninguno	No se utiliza

Tiempos de espera de los webhooks

Para el voice se pueden establecer tiempos de espera en los webhooks. Se pueden especificar dos tiempos de espera: connection_timeout y socket_timeout. Estos parámetros se aplican al answer, eventy fallback webhooks, y se expresan en milisegundos. La siguiente tabla ofrece más información:

Parámetro	Ejemplo	Descripción
`connection_timeout`	`1000`	Si Vonage no puede conectarse a la URL del webhook durante esta cantidad de tiempo especificada, entonces Vonage realiza un intento adicional para conectarse al punto final del webhook. Este es un valor entero especificado en milisegundos.
`socket_timeout`	`3000`	Si no se puede leer una respuesta de la URL del webhook durante esta cantidad de tiempo especificada, Vonage realizará un intento adicional para leer el punto final del webhook. Este es un valor entero especificado en milisegundos.

Al crear o actualizar una aplicación, estos parámetros pueden definirse directamente o actualizarse en función de las necesidades, por ejemplo:

...
  "capabilities": {
    "voice": {
      "webhooks": {
        "answer_url": {
          "address": "https://example.com/webhooks/answer",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        },
        "fallback_answer_url": {
          "address": "https://fallback.example.com/webhooks/answer",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        },
        "event_url": {
          "address": "https://example.com/webhooks/event",
          "http_method": "POST",
          "connection_timeout": 500,
          "socket_timeout": 3000
        }
      }
    }
...

Si no se especifican estos valores al crear o actualizar la aplicación, se aplicarán los valores por defecto. Los valores por defecto de estos tiempos de espera dependen del webhook en cuestión, tal y como se muestra en la siguiente tabla:

Gancho web	Por defecto `connection_timeout`	Por defecto `socket_timeout`
`answer`	1000	5000
`event`	1000	10000
`fallback`	1000	5000

NOTA: Los tiempos de espera se especifican en milisegundos.

Hay más explicaciones sobre los tiempos de espera de los webhooks en la sección documentación sobre webhooks.

Creación de aplicaciones

Hay cuatro formas principales de crear una aplicación:

En Vonage Panel de control. A continuación, las Applications aparecen en la lista tus aplicaciones sección del panel de control.
Utilización de la CLI de Vonage.
Utilización de la API de la aplicación.
Utilizando uno de los SDK de servidor.