Eventos de llamada
Todos los eventos que representan el estado de las llamadas telefónicas comparten campos y significados comunes; tanto si se entregan en respuesta a métodos de control de llamadas, o mediante consulta de eventos, como si se entregan a través de webhook. Todos los eventos de llamada tienen las siguientes propiedades:
| Propiedad | Descripción |
|---|---|
id |
El identificador único del evento |
userId |
El identificador de usuario VIS asociado al evento |
accountId |
El identificador de cuenta del VIS asociado al evento |
externalId |
El identificador del proveedor de comunicaciones externas. En las cargas útiles de los webhooks, contiene el ID de la llamada (a veces con un _{extension} (sufijo). |
direction |
INBOUND o OUTBOUND |
phoneNumber |
El número de teléfono de la parte remota |
callerId |
El nombre de la parte remota |
state |
El estado de la llamada; véase «Estados de los eventos» más abajo |
duration |
Duración de la llamada (en milisegundos) |
startTime |
Una fecha y hora según la norma ISO 8601 en la que se inició la llamada. En el caso de las llamadas salientes, la hora de inicio indica el momento en que se realizó la llamada; en el caso de las llamadas entrantes, indica la hora en que se recibió la llamada por primera vez. |
answerTime |
Una fecha/hora ISO-8601 en la que se respondió a la llamada |
endTime |
Una fecha/hora ISO-8601 en la que finalizó la llamada |
Webhook externalId y el identificador de llamada
En el caso de las cargas útiles de los webhooks, el ID de llamada y externalId se refieren al mismo identificador de llamada.
externalId suele presentarse con el siguiente formato: {call_id}_{extension}.
Ejemplo: abc1234-288c-40d3-8ec8-3618a3ae7698_123
Para extraer el ID de llamada de externalId, separado por un guión bajo (_) y tomar el primer elemento.
En el ejemplo anterior, el ID de llamada es: abc1234-288c-40d3-8ec8-3618a3ae7698
En algunos casos, externalId no puede contener un guión bajo. En ese caso, utiliza el nombre completo externalId valor como ID de llamada.
Estados de los eventos
Las API de VIS presentan un modelo de estados de eventos para las llamadas telefónicas, ocultando las diferencias y complejidades tanto de Vonage Business Communications como de Vonage Enterprise. Estos estados de eventos se proporcionan en respuesta a los métodos de las API (como «realizar llamada» o «obtener llamadas») y se incluyen en las notificaciones de eventos de webhook. Comprender el modelo de estados de eventos es fundamental para desarrollar integraciones externas.
La siguiente máquina de estados finitos describe las transiciones de estado permitidas:
El único estado inicial es Initializing. Los únicos estados finales permitidos son Answered, Cancelled, Rejectedy Missed. Los estados de llamada en uno de los estados finales siempre permanecerán en el estado final.
| Estado | Inicial | Final | Dirección | Transiciones permitidas | Descripción |
|---|---|---|---|---|---|
| Inicialización de | Sí | No | Entrada | Timbre, Contestado | Se ha realizado una llamada, pero aún no se ha avisado a la parte remota. |
| Timbre | No | No | Entrada, Salida | Activo, Contestado, Cancelado, Rechazado, Desaparecido | Se está avisando al interlocutor remoto (saliente) o se está produciendo una llamada entrante |
| Activo | No | No | Entrada, Salida | Contestado, Retenido, Retenido a distancia | Hay una llamada en curso y los participantes están hablando |
| Celebrado | No | No | Entrada, Salida | Activo | Hay una llamada activa en espera |
| A distancia | No | No | Entrada, Salida | Activo | Una parte remota de una llamada activa está actualmente en espera |
| Respondido | No | Sí | Entrada, Salida | Ha finalizado una llamada de duración distinta de cero | |
| Cancelado | No | Sí | Salida | Se ha cancelado una llamada saliente antes de que el destinatario contestara. | |
| Falta | No | Sí | Entrada | No se ha respondido a una llamada entrante | |
| Rechazado | No | Sí | Entrada | Una llamada entrante ha sido rechazada o enviada al buzón de voz sin ser contestada |
Para cada estado, los valores de startTime, answerTime, endTimey duration seguirá ciertas reglas.
Todos los estados de llamada tendrán un startTime. Sólo Active, Held, Remote Heldy Answered tendrá un answerTime.
El endTime permanecerá nula hasta que la llamada alcance un estado final (Answered, Cancelled, Missed, Rejected).
Sólo las convocatorias que hayan alcanzado el Answered tendrá una duración distinta de cero.
Obtener eventos de llamada
La API permite recuperar eventos de llamada para llamadas activas o finalizadas. Dado que el número de registros de eventos de llamada puede ser numeroso, la respuesta puede paginarse. Normalmente, las Applications recuperan el número total de registros para un conjunto concreto de parámetros de consulta y, a continuación, recuperan los eventos en un intervalo de varias llamadas a la API utilizando el mismo conjunto de parámetros de consulta y un número máximo de eventos a devolver por llamada.