Convocar eventos
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 | Id. único del evento |
userId | El identificador de usuario VIS asociado al evento |
accountId | Account id del VIS asociado al evento |
externalId | Id. único del evento proporcionado por el proveedor de comunicaciones externas, utilizado únicamente con fines informativos. |
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, ver Estados de Eventos más abajo |
duration | Duración de la llamada (en milisegundos) |
startTime | Una fecha/hora ISO-8601 en la que se inició la llamada. Para llamadas salientes, la hora de inicio marca el momento en que se realiza la llamada; para llamadas entrantes, marca el momento en que se recibe 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 |
Estados del acontecimiento
Las VIS API presentan un modelo de estado de eventos para llamadas telefónicas, ocultando las diferencias y complejidades de Vonage Business Communications y Vonage Enterprise. Estos estados de eventos se entregan en respuesta a las API de métodos (como realizar llamada, obtener llamadas) y se incluyen en las notificaciones de eventos de webhook. Comprender el modelo de estado de eventos es fundamental para crear 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 | Una llamada está activa y los participantes están hablando |
| En | 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 |
| Respuesta | 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 respondiera el interlocutor remoto | |
| 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.
En 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.
Obtención de 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.