Webhooks / Callbacks Totalvoice

Webhooks são a melhor forma de integrar com seu sistema – são POSTs HTTP que ocorrem em determinados eventos enviando informações para seu sistema. Prefira o uso de webhooks ao invés de consultas em loop para otimizar recursos.

C configuração dos webhooks é feita através do painel, em “Configurações da API”.

 

 

Chamadas

Final de Ligação

Toda vez que uma ligação termina, este webhook é disparado.

  • O fim de uma ligação ocorre quando ela foi atendida e encerrou (chamada atendida) ou não foi atendida por algum outro motivo.
  • Status possíveis: (atendida, sem resposta, ocupado, congestionado, falha).
  • O status “ativa” é retornado como FALSE.
  • A URL do webhook pode ser configurada dentro do painel no menu “minha conta” / “Configurações da API” ou pela API (acessar documentação).
  • Repare que existem diversos tipos de webhooks de fim de chamada: chamada_fim, tts_fim, composto_fim e audio_fim.

 

Formato dos dados chamada_fim:

{  
   "id":3273692,
   "data_criacao":"2018-08-15T08:22:30-03:00",
   "ativa":false,
   "url_gravacao":null,
   "cliente_id":6226380,
   "conta_id":6226380,
   "ramal_id_origem":null,
   "tags":"clienteX",
   "status_geral":"finalizada",
   "origem":{  
      "data_inicio":"2018-08-15T08:22:32-03:00",
      "numero":"1130505001",
      "tipo":"fixo",
      "status":"atendida",
      "duracao_segundos":0,
      "duracao":"00:00:00",
      "duracao_cobrada_segundos":0,
      "duracao_cobrada":"00:00:00",
      "duracao_falada_segundos":0,
      "duracao_falada":"00:00:00",
      "preco":0,
      "motivo_desconexao":"16. normal"
   },
   "destino":{  
      "data_inicio":"2018-08-15T08:22:32-03:00",
      "numero":"7171",
      "tipo":"ramal",
      "status":"atendida",
      "duracao_segundos":0,
      "duracao":"00:00:00",
      "duracao_cobrada_segundos":0,
      "duracao_cobrada":"00:00:00",
      "duracao_falada_segundos":0,
      "duracao_falada":"00:00:00",
      "preco":0,
      "motivo_desconexao":"indefinido"
   }
}

 

 

Formato dos dados tts_fim:

{  
   "id":7453678,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T08:21:45-03:00",
   "data_inicio":"2018-08-15T08:21:45-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":9,
   "duracao":"00:00:09",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":9,
   "duracao_falada":"00:00:09",
   "preco":0.06,
   "mensagem":"Esta é uma mensagem SMS",
   "velocidade":0,
   "resposta_usuario":false,
   "resposta":""
}

 

Formato dos dados composto_fim:

{  
   "id":1722497,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T10:44:03-03:00",
   "data_inicio":"2018-08-15T10:44:04-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":10,
   "duracao":"00:00:10",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":10,
   "duracao_falada":"00:00:10",
   "preco":0.06,
   "resposta_usuario":false,
   "resposta":null,
   "tags":null,
   "motivo_desconexao":"16. normal",
   "url_gravacao":null
}

 

Formato dos dados audio_fim:

{  
   "id":3273691,
   "numero_destino":"1130505001",
   "data_criacao":"2018-08-15T08:22:22-03:00",
   "data_inicio":"2018-08-15T08:22:23-03:00",
   "tipo":"fixo",
   "status":"atendida",
   "duracao_segundos":10,
   "duracao":"00:00:10",
   "duracao_cobrada_segundos":60,
   "duracao_cobrada":"00:01:00",
   "duracao_falada_segundos":10,
   "duracao_falada":"00:00:10",
   "preco":0.06,
   "url_audio":"https://foooo.bar/audio.mp3",
   "resposta_usuario":false,
   "resposta":"",
   "url_gravacao":null
}

 

Formato dos Dados

O envio dos dados ocorre via HTTP (ou HTTPS) com o seguinte header:

“Content-type: application/json”

 

Este é um breve exemplo em PHP para receber os dados:

 <?php
 $json_dados= file_get_contents("php://input");
 $LOGFILE = __DIR__."/log.txt";
 $pf = fopen($LOGFILE, "a+");
 fwrite($pf, date('Y/m/d H:i:s'));
 fwrite($pf, "\n".$json_dados."\n\n");
 $array_dados = json_decode($json_dados, true);
 fwrite($pf, "ID>".$array_dados['id']."\n");
 fclose($pf);
 ?>
Não esqueça de criar o arquivo log.txt e dar permissão de escrita para o usuário web.

Resultado:

 more log.txt
 2017/03/16 18:34:20{"id":4163,"sms_id":1092334,"resposta":" 3","data_resposta":"2017-03-16T15:34:20-03:00"}

Webhook em Tempo Real

Estes Webhooks são disparados conforme o status da ligação se modifica. São importantes para sistemas de acompanhamento de chamadas em tempo real, como exibir uma notificação caso esteja chegando uma chamada para um ramal, por exemplo.

As informações de atendimento, como duração, data de atendimento e duração falada só vem após o atendimento de determinado destino / origem.

O campo status pode ter os seguintes valores: preparando, chamando, atendida, ocupado.

O campo ativo informa se a chamada em determinado destino / origem está ativa (linha aberta / na linha), tendo como valor apenas true / false.

Chamadas em Tempo Real

Toda vez que uma das pernas da ligação muda de estado, este webhook é disparado, entram nessas condições apenas ligações realizadas pela API e pelo Webphone/Softphone/Dispositivo de Chamada conectado ao nosso sistema.

Formato dos dados postados para a URL do webhook:

{
   "data_criacao":"2018-06-08T13:20:29",
   "gravar_audio":false,
   "id":121947,
   "cliente_id":111111,
   "tags":"MINHA_TAG,CLIENTE_LEGAL",
   "origem":{
      "data_criacao":"2018-06-08T10:20:31",
      "tipo":"ramal",
      "ativo":true,
      "numero":"4000",
      "status":"atendida",
      "data_atendimento":"2018-06-08T10:20:34",
      "duracao_segundos":9,
      "duracao_falada_segundos":6
   },
   "destino":{
      "data_criacao":"2018-06-08T10:20:34",
      "tipo":"movel",
      "ativo":false,
      "numero":"489999999999",
      "status":"chamando"
   }
}

Ramal em Tempo Real

Toda vez que algum ramal da conta configurada com esse Webhook recebe/atende/desliga uma ligação um evento desse é disparado para a URL escolhida.

O número origem é o número de telefone que está em ligação com este ramal para este ramal.

Formato dos dados postados para a URL do webhook:

{
   "data_criacao":"2018-06-08T10:20:31",
   "id":121947,
   "tipo":"ramal",
   "ativo":true,
   "ramal":"4000",
   "numero_origem":4899999999,
   "status":"atendida",
   "data_atendimento":"2018-06-08T10:20:34",
   "duracao_segundos":9
   "duracao_falada_segundos":6,
   "tags":"MINHA_TAG,CLIENTE_LEGAL"
}

DID em Tempo Real

Um evento deste é disparado sempre que um DID (número de telefone) nosso de um cliente cadastrado com esse Webhook recebe uma ligação ou muda de status (transfere, termina, etc).

O campo ramal só será preenchido caso a ligação que foi para o DID acabe caindo em algum ramal.

Número origem é o número que ligou para o DID e o destino é o DID que está recebendo a ligação.

Formato dos dados postados para a URL do webhook:

{
   "id":121947,
   "data_criacao":"2018-06-08T13:20:29",
   "gravar_audio":false,
   "cliente_id":111111,
   "numero_origem":"4822221111",
   "numero_destino":"4833332222",
   "data_atendimento":"2018-06-08T10:20:34",
   "ativo":true,
   "data_criacao":"2018-06-08T10:20:31",
   "status":"atendida",
   "duracao_segundos":20,
   "duracao_falada_segundos":19,
   "ramal":{
      "ativo":true,
      "data_criacao":"2018-06-08T10:20:34",
      "numero":"4000",
      "status":"atendida",
      "duracao_segundos":9,
      "duracao_falada_segundos":6,
   }
}

 

 

 

 

SMS

SMS – Mudança de Status e Entrega

Este webhook é disparado sempre que uma mensagem SMS sofrer uma mudança de status.

  • Status possíveis: aguardando, enviada, erro, entregue.

Conteúdo do Webhook

Formato dos dados postados para a URL do webhook:

{
        "id": 2323,
        "numero_destino": "9912341234",
        "data_criacao": "2016-04-05T15:00:34-03:00",
        "mensagem": "Texto mensagem SMS",
        "preco": 0.15,
        "status_envio": "entregue",
        "data_status": "2016-04-05T15:01:23-03:00",
        "resposta_usuario": 1,
        "respostas": [
                {
                        "id": 3301,
                        "resposta": "Texto da Resposta",
                        "data_resposta": "2016-04-05T15:05:13-03:00"
                },
                {
                        "id": 3302,
                        "resposta": "Outra resposta",
                        "data_resposta": "2016-04-05T15:07:11-03:00"
                }

        ]
}

Resposta de SMS

O webhook de resposta de SMS é um JSON com ID do retorno, ID do SMS, resposta e data.

 

Exemplo:

{"id":16347,"sms_id":133830,"resposta":"SIM","data_resposta":"2016-10-17T18:02:20-02:00"}