Ir para o conteúdo

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

webhooks-config.png

Figure 9.1 Ativação e configuração de Webhooks.
  1. Clique em Integrações.
  2. Desça até aos Webshooks e escolha Ativar.
  3. Seleccione Adicionar Webshooks para criar um novo.
  4. Introduza qualquer nome para o novo Webshook da Rede a identificar.
  5. Selecione eventos para ouvir. Nota Call State change inclui todos os eventos.
  6. Digite o URL utilizado pela sua aplicação.
  7. Para Editar qualquer tipo de Webhooks basta clicar sobre o nome.
  8. 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.

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

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:

webhooks-troubleshooting.png

Figure 9.2 Resolução de problemas Webhooks.
  1. A partir do painel de administração abrir a secção História do painel.
  2. Clique em CDR, isto abrirá uma lista com chamadas recentes processadas sob a plataforma VoIPstudio.
  3. Identificar e clicar na chamada que deseja inspeccionar para abrir informações detalhadas da chamada correspondente.
  4. Em fluxo de chamadas identifique a coluna do seu servidor API.
  5. Deve ver um pedido de POST enviado para o servidor para cada evento que tenha definido como evento Webhook. Clique sobre ele para expandir.
  6. Os detalhes da resposta do Webhook são mostrados aqui.