Como configurar e testar Webhooks no Umbler Talk

O que são webhooks?
Webhooks são chamadas feitas em tempo real para seu URL personalizado quando qualquer evento é acionado no WhatsApp.

Por ex: Quando uma nova mensagem é recebida/enviada ou se houver alteração de status de uma mensagem que foi enviada, como: "Lido" ou "Entregue". O sistema dispara a notificação para SEU URL.

Para que você tenha acesso a essa configuração é necessário acessar o site do Umbler Talk e realizar login com email e senha de cadastro.

Ao acessar o painel, no menu superior, clique sobre Módulos > Integrações API/Webhook.
Você será redirecionado à página de Integrações API/Webhook, nas opções ao lado, clique sobre Configurar Webhook.

Nessa página você pode navegar em 3 abas:

Configurar:

No campo para digitação, cole a URL desejada e clique em Salvar.
Pronto! A URL foi configurada e todos os eventos vão ser direcionados à ela.

Como funciona?

Nessa seção você poderá conferir exemplos de eventos enviados.

Evento: Nova mensagem enviada/recebida
URL: O Umbler Talk irá realizar uma requisição POST para seu URL
Method: POST
Request (POST form)

event: chat
token: Seu token do Umbler Talk
user: Número de telefone da sua conta WhatsApp com código internacional
contact[number]: Número de telefone da conta do remetente WhatsApp
contact[name]: Nome da conta do remetente WhatsApp
contact[server]: Tipo de chat. c.us = Contato e g.us = Grupo
chat[dtm]: Mensagem enviada. timestamp
chat[uid]: MSG ID exclusiva do WhatsApp para esta mensagem: 62397B58E3E0B
chat[dir]: Direção da mensagem Ex: i (msg recebida) Ex: o (msg enviada)
chat[type]: Tipo de mensagem Ex: chat, image, video, audio, document, vcard, location
chat[body]: Conteúdo da mensagem.
ack Confirmação do status da mensagem.

Evento: Confirmação (ACK)
URL: O Umbler Talk irá realizar uma requisição POST para seu URL
Method: POST
Request (POST form)

event: ack
token: Seu token do Umbler Talk
number: Número de telefone da conversa que foi enviada a mensagem
server:  Tipo de chat. c.us = Contato e g.us = Grupo
user: Número de telefone da sua conta WhatsApp com código internacional
id: ID exclusivo do WhatsApp para esta mensagem
muid: MSG ID exclusiva personalizada para esta mensagem, se enviado por você.
id: MSG ID exclusiva gerada pelo WhatsApp.
ack: Status da mensagem.

(ACK) Confirmação de status

Tipo | Status
0 Mensagem ainda não enviada para os servidores do WhatsApp
1 Mensagem enviada para servidores WhatsApp
2 Mensagem entregue ao destinatário
3 Mensagem lida pelo destinatário
(Observação: Pode ser mascarado como status "2" dependendo das configurações de privacidade do destinatário)

Simule uma requisição do Umbler Talk para seu URL:

Nessa seção é possível simular o envio de eventos para um URL.
Para simular você deve selecionar o tipo de evento e inserir a URL desejada.

Simulando ações de envio

Para realizarmos esse teste, vamos utilizar o site webhook.site, através dele temos disponível um URL para recebimento desses eventos.

Acesse o webhook.site, você verá essa página:

Será disponibilizado uma URL única:

Clique em Copy to clipboard, ou selecione o URL e copie. Cole a URL disponibilizada no painel do Umbler Talk para realizar as simulações de envio:

Mensagem enviada pela API/Aparelho:

Para realizar a simulação, selecione o tipo de evento e clique em “Enviar simulação para URL”.

Será retornado em JSON o que foi enviado para a URL:

{"event":"chat","token":"token-da-sua-conta","user":"55119XXXXXXXX","operador":"xxxxx","contact[number]":"5511984459878","contact[name]":"Fake name","contact[server]":"c.us","chat[dtm]":"1550759821","chat[uid]":"FN45VQIOVF8BINHTHUA3","chat[dir]":"o","chat[type]":"chat","chat[body]":"Message test","ack":"-1"}

Na página do webhook.site o evento já foi enviado:

Na listagem esquerda, serão listados todas as requisições/eventos enviados para essa URL.

Em form values, são todos os valores do evento enviado.

Esses são os mesmos valores enviados em JSON mostrados no painel do Umbler Talk:

event	chat
token	token-da-sua-conta
user	55119XXXXXXXX
operador	xxxxx
contact	{"number":"5511984459878","name":"Fake name","server":"c.us"}
chat	{"dtm":"1550759821","uid":"FN45VQIOVF8BINHTHUA3","dir":"o","type":"chat","body":"Message test"}
ack	-1

Mensagem recebida:

Para outros tipos de evento, o procedimento será o mesmo. Selecione o evento desejado, nesse caso, mensagem recebida e clique em “Enviar simulação para URL”:

{"event":"chat","token":"token-da-sua-conta","operador":"xxxxx","user":"55119XXXXXXXX","contact[number]":"5511984459878","contact[name]":"Fake name","chat[dtm]":"1550759821","chat[uid]":"36TZTHHSVTGPLR8H8ZIS","chat[dir]":"i","chat[type]":"chat","chat[body]":"Message test","ack":"-1"}

No webhook.site a requisção já foi recebida e listada:

Mídia com miniatura:

Para realizar a simulação, selecione o tipo de evento e clique em “Enviar simulação para URL”.

Será retornado em JSON o que foi enviado para a URL:

{"event":"chat","token":"token-da-sua-conta","user":"55119XXXXXXXX","contact[number]":"5511984459878","contact[name]":"Fake name","chat[dtm]":"1550759821","chat[uid]":"GGXZTORQUCSP6HEDFPZU","chat[dir]":"i","chat[type]":"image","chat[body]":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDABQODxIPDRQ....","chat[fn]":"405C330540C2D7045E5DC1CD656E7D0D.jpg","ack":"-1"}

event	chat
token	token-da-sua-conta
user	55119XXXXXXXX
contact	{"number":"5511984459878","name":"Fake name"}
chat	{"dtm":"1550759821","uid":"GGXZTORQUCSP6HEDFPZU","dir":"i","type":"image","body":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDABQODxIPDRQ....","fn":"405C330540C2D7045E5DC1CD656E7D0D.jpg"}
ack	-1

Recebimento de mídia (Base64 completo):

Para realizar a simulação, selecione o tipo de evento e clique em “Enviar simulação para URL”.

Será retornado em JSON o que foi enviado para a URL:

{"event":"file","token":"token-da-sua-conta","fn":"405C330540C2D7045E5DC1CD656E7D0D.jpg","blob":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA..."}

Para mídias, sempre será enviado uma event file separadamente, nesse event file será disponibilizada a mídia enviada pelo WhatsApp. As mídias são enviadas pelo método base64, que é um método de decodificação.

Quando receber esse arquivo, você deve decodificá-lo para utilização.

Caso você envie uma mensagem com uma imagem, por exemplo, você receberá dois eventos, um event chat com a imagem base64 no corpo da mensagem e um event file separado, somente com a mídia dentro do parâmetro blob.

Confirmação de status (ACK):

Para realizar a simulação, selecione o tipo de evento e clique em “Enviar simulação para URL”.

Será retornado em JSON o que foi enviado para a URL:

{"event":"ack","token":"token-da-sua-conta","user":"55119XXXXXXXX","muid":"MQUSR313M6XVHOBLEUOH","id":"1E51LFO46A","ack":"2"}

Na simulação de envio, receberemos 2 eventos com dois status ack diferentes.

No primeiro, ele recebeu o ACK: 1 que significa que a mensagem foi enviada.

No segundo evento, o ACK retornou o status 2, que significa que a mensagem foi entregue:

Eventos em tempo real

Configurando um URL na sua conta, enquanto estiver conectado no Umbler Talk, toda a atividade do seu WhatsApp será enviado para a URL, pelo celular, WebChat do Umbler Talk ou API.

Após definir o URL, clique em Salvar. A partir de agora, todos os eventos serão enviados.

Ao iniciar a conexão, você receberá um webhook de login:

Será informado o evento do tipo login, informando o número, horário, token, webhook e servidor que foi iniciado.

Conforme as mensagens são enviadas, os eventos vão sendo listados.

Essa é uma troca de mensagens dentro do Umbler Talk:

A primeira mensagem enviada e o webhook recebe um event chat, nesse evento, ele recebe as informações listadas:

O token utilizado, o user será o número utilizado/conectado, o operador que enviou a mensagem. Em contact, são as informações do contato vinculado à conversa.

Já em chat, são as informações da conversa.

O ACK é o status de envio, que neste momento está em 0, que significa que a mensagem ainda não tinha sido enviada aos servidores do WhatsApp.

Recebemos também separadamente eventos ACK, informando cada modificação no status. Ao ser enviada, ela retorna o status 1:

Ao ser entregue, retorna o status 2:

E ao ser lida, retorna o status 3:

Ao receber a resposta, você receberá um novo event chat com a nova mensagem:

Após a nova mensagem, foi enviada uma imagem, primeiramente, você receberá um event chat com a base64 da imagem no corpo da mensagem:

E logo depois, um event file separado somente com a imagem, o parâmetro fn é o nome do arquivo e o blob, onde é armazenado a imagem:

Decodificando a imagem:

Para exemplificar, vamos utilizar este site que converte a base64 para JPEG. Dentro do webhook, vamos copiar o valor do parâmetro blob:

Dentro do conversor, vamos colar dentro de input base64:

Ficará desta forma, já com a imagem formatada:

É possível salvar e utilizar a imagem recebida: