Integrações - Webhooks¶
"Webhooks são desencadeados por Evento de Chamada, tais como toque de chamada, chamada atendida, chamada suspensa, etc. Quando esse evento ocorre, a plataforma VoIPstudio faz um pedido HTTPS (POST) para o URL configurado para o Webhook - um servidor web de terceiros (API). Ver mais em Wikipedia
- Clique em Integrações.
- Desça até aos Webshooks e escolha Ativar.
- Seleccione Adicionar Webshooks para criar um novo.
- Introduza qualquer nome para o novo Webshook da Rede a identificar.
- Selecione eventos para ouvir. Nota
Call State change
inclui todos os eventos. - Digite o URL utilizado pela sua aplicação.
- Para Editar qualquer tipo de Webhooks basta clicar sobre o nome.
- Se já não for necessário, basta clicar em desactivar os Webshooks.
NOTA: Apenas o Protocolo HTTPS é suportado.
NOTA: Para que o URL seja guardado, tem de ser válido e responder aos pedidos https.
Eventos disponíveis¶
Com o VoIPtudio WebHooks monitorizamos as categorias de eventos do estado da chamada:
- Chamada perdida
- Chamada a tocar
- Chamada ligada
- Chamada terminada
- Call State Change - este último inclui todos os tipos de eventos anteriores. É desencadeada para qualquer mudança de estado de chamada:INICIAL, TOQUE, LIGADO, ON_HOLD, DESLIGAR.
Nota: Os eventos monitorizados mostram o estado da chamada e estão a corresponder às mensagens de sinalização SIP, conforme detalhado abaixo:
- INTITAL: SIP INVITE enviar para o ponto final correspondente (Telefone).
- RINGING: resposta do ponto final do SIP INVITE. Indica que o endpoint está activo e já está a tocar.
- CONNECTED: SIP 200 mensagem indicando que o utilizador respondeu à chamada.
- ON_HOLD: A chamada fez uma pausa. Isto corresponde a SIP INVITE com
body: a=sendonly
. - HANGUP: indicando que a chamada terminou. Isto corresponde à mensagem SIP BYE.
Para além dos eventos do estatuto de chamada, estão disponíveis os seguintes eventos adicionais:
- SMS Recebidos
Atributos do evento¶
Os eventos são entregues como pedidos POST HTTPs com o corpo JSON - por exemplo:
{
"id":"uk003.608920d55f7ac3.77053295",
"event_time":"2021-04-28 08:46:13",
"event_name":"call.hangup",
"call_id":139543232,
"state":"HANGUP",
"connected_at":"2021-04-28 08:46:02",
"start_time":"2021-04-28 08:45:55",
"context":"LOCAL_USER",
"destination":"in",
"duration":11,
"t_cause":"Normal Clearing",
"src":"447854740947",
"src_id":"0",
"src_name":"\"442035141598\" <2035141598>",
"dst":"441183211001",
"dst_id":"10002",
"dst_name":"John Smith"
}
Os atributos são os seguintes:
id
(string) - identificação única de um Eventoevent_time
(string) - hora de um Evento em formato Y-m-d H:i:s fuso horário UTCevent_name
(string) - nome de um Evento, um de:call.initial
- Chamada em estado inicialcall.ringing
- Chamada a tocarcall.missed
- Chamada perdida (sem resposta)call.connected
- Chamada está ligadacall.hangup
- Chamada terminadacall.hold
- Chamada é colocada em esperacall.unhold
- A chamada é retomada
call_id
(integer) - esta é a identificação numérica da chamada. Pode ser utilizado mais tarde para aceder a recursos através de REST API. A relação com os recursos REST API é:call.id
- example REST API request:cdr.live_id
- exemplo de pedido REST API: GET/v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
monitor.live_id
- exemplo de pedido REST API: GET/v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
state
(string) - estado da Chamada, uma das:INITIAL
- Estado de chamada inicialACCEPTED
- Clique 2 chamada foi aceiteRINGING
- O destino está a tocarCONNECTED
- A chamada está conectadaON_HOLD
- Chamada em esperaHANGUP
- Chamada terminada
connected_at
(string) - hora em que a chamada foi ligada no formato Y-m-d H:i:s UTC timezone. Predefiniçãonull
start_time
(string) - hora em que a chamada começou no formato Y-m-d H:i:s UTC timezone.context
(string) - contexto da chamada dentro do sistema PBXdestination
(string) -in
para chamadas recebidas,out
para chamadas de saídaduration
(integer) - a duração da chamada é de segundost_cause
(string) - Causa da terminaçãosrc
(string) - Número da origem da chamadasrc_id
(integer) - Identificação numérica da origem da chamadasrc_name
(string) - Nome da origem da chamadadst
(string) - Número do destino da chamadadst_id
(integer) - Identificação numérica do destino da chamadadst_name
(string) - Nome do destino da chamada
Os atributos de eventos recebidos por SMS são os seguintes:
id
(string) - identificação única de um Eventoevent_time
(string) - hora de um Evento no formato Y-m-d H:i:s UTC timezonenome_do_evento
(string) - nome de um Evento `sms.recebido'.customer_id
(integer) - Identificação numérica da conta do cliente que recebeu a mensagem SMSuser_id
(integer) - ID numérico da conta de utilizador que recebeu a mensagem SMS (opcional, por defeito:null
)from_no
(string) - número de telefone de origemto_no
(string) - número de telefone que recebeu mensagem SMStexto
(string) - corpo da mensagem recebida
Endpoints REST API relacionados¶
Depois de receber o evento Webhook como no exemplo acima (call_id
= 139543232
), é possível recuperar e actualizar o recurso de Chamada via REST API:
GET /v1.1/calls/139543232
e para Transferir a chamada para a extensão `2002'.:
PATCH /v1.1/calls/139543232
{
"dst": "2002"
}
Nota: /calls
REST API recurso representa chamada em curso activa. Uma vez terminada a chamada e recebido o evento call.hangup
já não está disponível no ponto final /calls
. Em vez disso, pode ser acedido em /cdrs
(Call Details Report) e /monitors
(Call Recordings) endpoints utilizando filtro no atributo live_id
com valor de call_id
do evento Webhook, por exemplo:
GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"139543232"}]
or
GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"139543232"}]
Resolução de problemas Webhooks¶
Os relatórios detalhados de VoIPstudio dashboard permitem aos clientes monitorizar todos os fluxos de trabalho dos pacotes SIP numa vista gráfica para cada chamada. Também exibe as notificações de Webhooks enviadas para o seu URL de escuta, incluindo o seu conteúdo. Isto pode ser muito útil para resolver problemas de implementação de notificações de Webhooks.
Basta consultar o Relatório Detalhado de Chamadas e clicar nas chamadas correspondentes e verificar os eventos submetidos e o seu conteúdo. Isto deve corresponder à notificação que recebeu no servidor. Por favor, siga os passos abaixo:
- A partir do painel de administração abrir a secção
História
do painel. - Clique em
CDR
, isto abrirá uma lista com chamadas recentes processadas sob a plataforma VoIPstudio. - Identificar e clicar na chamada que deseja inspeccionar para abrir informações detalhadas da chamada correspondente.
- Em fluxo de chamadas identifique a coluna do seu servidor API.
- Deve ver um pedido de POST enviado para o servidor para cada evento que tenha definido como evento Webhook. Clique sobre ele para expandir.
- Os detalhes da resposta do Webhook são mostrados aqui.