Eventos de chamada
Todos os eventos que representam o status das chamadas telefônicas compartilham campos e significados comuns, independentemente de serem transmitidos em resposta a métodos de controle de chamadas, por meio de consultas a eventos ou via webhook. Todos os eventos de chamada possuem as seguintes propriedades:
| Propriedade | Descrição |
|---|---|
id |
O identificador único do evento |
userId |
O ID de usuário do VIS associado ao evento |
accountId |
O ID da conta VIS associado ao evento |
externalId |
O identificador do provedor de comunicações externas. Nas cargas úteis dos webhooks, ele contém o ID da chamada (às vezes com um _{extension} sufixo). |
direction |
Seja INBOUND ou OUTBOUND |
phoneNumber |
O número de telefone da outra parte |
callerId |
O nome da parte remota |
state |
O estado da chamada; consulte “Estados de eventos” abaixo |
duration |
A duração da chamada (em milissegundos) |
startTime |
Uma data e hora no formato ISO-8601 correspondente ao início da chamada. Para chamadas efetuadas, a hora de início indica o momento em que a chamada foi feita; para chamadas recebidas, indica o momento em que a chamada foi recebida pela primeira vez |
answerTime |
Data e hora no formato ISO-8601 em que a chamada foi atendida |
endTime |
Uma data e hora no formato ISO-8601 correspondentes ao momento em que a chamada foi encerrada |
Webhook externalId e identificação de chamada
Para cargas úteis de webhooks, o ID da chamada e externalId referem-se ao mesmo identificador de chamada.
externalId é normalmente formatado como {call_id}_{extension}.
Exemplo: abc1234-288c-40d3-8ec8-3618a3ae7698_123
Para extrair o ID da chamada de externalId, separado por sublinhado (_) e selecionar o primeiro elemento.
No exemplo acima, o ID da chamada é: abc1234-288c-40d3-8ec8-3618a3ae7698
Em alguns casos, externalId não pode conter um sublinhado. Nesse caso, use o nome completo externalId valor como ID da chamada.
Estados do evento
As APIs do VIS apresentam um modelo de estados de eventos para chamadas telefônicas, ocultando as diferenças e complexidades tanto do Vonage Business Communications quanto do Vonage Enterprise. Esses estados de eventos são fornecidos em resposta a métodos das APIs (como “fazer chamada” e “obter chamadas”) e incluídos nas notificações de eventos via webhook. Compreender o modelo de estados de eventos é fundamental para a criação de integrações externas.
A máquina de estados finitos a seguir descreve as transições de estado permitidas:
O único estado inicial é Initializing. Os únicos estados finais permitidos são Answered, Cancelled, Rejected, e Missed. Os estados de chamada que se encontram em um dos estados finais permanecerão sempre nesse estado final.
| Estado | Inicial | Final | Direção | Transições permitidas | Descrição |
|---|---|---|---|---|---|
| Inicializando | Sim | Não | Entrada | Toque, atendido | Foi feita uma chamada, mas o destinatário ainda não foi notificado |
| Zumbido | Não | Não | Entrada, Saída | Ativo, Respondido, Cancelado, Rejeitado, Ausente | A outra parte está sendo alertada (chamada de saída) ou está ocorrendo uma chamada recebida |
| Ativo | Não | Não | Entrada, Saída | Respondido, Retido, Retido remotamente | A chamada está ativa e os participantes estão falando |
| Realizado | Não | Não | Entrada, Saída | Ativo | Uma chamada ativa está atualmente em espera |
| Realizado remotamente | Não | Não | Entrada, Saída | Ativo | Um participante remoto de uma chamada ativa está, no momento, em espera |
| Respondido | Não | Sim | Entrada, Saída | Uma chamada com duração diferente de zero foi encerrada | |
| Cancelado | Não | Sim | Saída | Uma chamada efetuada foi cancelada antes que o destinatário atendesse | |
| Perdeu | Não | Sim | Entrada | Uma chamada recebida não foi atendida | |
| Rejeitado | Não | Sim | Entrada | Uma chamada recebida foi rejeitada ou encaminhada para a caixa postal sem ter sido atendida |
Para cada estado, os valores de startTime, answerTime, endTime, e duration seguirá certas regras.
Todos os estados da chamada terão um startTime. Apenas Active, Held, Remote Held, e Answered terá um válido answerTime.
O endTime a propriedade permanecerá nula até que a chamada chegue a um estado final (Answered, Cancelled, Missed, Rejected).
Apenas as ligações que chegaram à final Answered o estado terá uma duração diferente de zero.
Obtendo eventos de chamada
A API permite recuperar eventos de chamadas, tanto para chamadas ativas quanto para chamadas encerradas. Como o número de registros de eventos de chamadas pode ser elevado, a resposta pode ser dividida em páginas. Normalmente, as applications recuperam o número total de registros para um determinado conjunto de parâmetros de consulta e, em seguida, recuperam os eventos ao longo de várias chamadas à API, utilizando o mesmo conjunto de parâmetros de consulta e um número máximo de eventos a serem retornados por chamada.