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

Figure 68.1 Ativação e configuração de Webhooks.

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 Evento
event_time (string) - hora de um Evento em formato Y-m-d H:i:s fuso horário UTC
event_name (string) - nome de um Evento, um de:
- call.initial - Chamada em estado inicial
- call.ringing - Chamada a tocar
- call.missed - Chamada perdida (sem resposta)
- call.connected - Chamada está ligada
- call.hangup - Chamada terminada
- call.hold - Chamada é colocada em espera
- call.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 inicial
- ACCEPTED - Clique 2 chamada foi aceite
- RINGING - O destino está a tocar
- CONNECTED - A chamada está conectada
- ON_HOLD - Chamada em espera
- HANGUP - Chamada terminada
connected_at (string) - hora em que a chamada foi ligada no formato Y-m-d H:i:s UTC timezone. Predefinição null
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 PBX
destination (string) - in para chamadas recebidas, out para chamadas de saída
duration (integer) - a duração da chamada é de segundos
t_cause (string) - Causa da terminação
src (string) - Número da origem da chamada
src_id (integer) - Identificação numérica da origem da chamada
src_name (string) - Nome da origem da chamada
dst (string) - Número do destino da chamada
dst_id (integer) - Identificação numérica do destino da chamada
dst_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 Evento
event_time (string) - hora de um Evento no formato Y-m-d H:i:s UTC timezone
nome_do_evento (string) - nome de um Evento `sms.recebido'.
customer_id (integer) - Identificação numérica da conta do cliente que recebeu a mensagem SMS
user_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 origem
to_no (string) - número de telefone que recebeu mensagem SMS
texto (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:

Figure 68.2 Resolução de problemas Webhooks.

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.