Tutoriais

Atendimento em horário comercial via chat

Como configurar e testar Webhooks no uTalk

 

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 uTalk 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.

 

 

image32.png

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.

image3.png

Como funciona?

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

image28.png

  • Evento: Nova mensagem enviada/recebida
  • URL: O uTalk irá realizar uma requisição POST para seu URL
  • Method: POST
  • Request (POST form)
event: chat
token: Seu token do uTalk
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 uTalk irá realizar uma requisição POST para seu URL
  • Method: POST
  • Request (POST form)
event: ack
token: Seu token do uTalk
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 uTalk 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.


image2.png

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:
image33.png

Será disponibilizado uma URL única:

image30.png

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

image26.png

Mensagem enviada pela API/Aparelho:

image10.png

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:

image16.png

 

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

image24.png

 

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

image31.png

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

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:

image4.png
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:

image5.png

 

Mídia com miniatura: 

image18.png

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"}

image12.png

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):
image8.png

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..."}

image7.pngPara 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):

image17.png

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.

image27.png

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

image25.png

 


 

Eventos em tempo real

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

image26.png

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:

image21.png

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.

image34.png

 

Essa é uma troca de mensagens dentro do uTalk:

image6.png

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

image11.png

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:

image35.png

Ao ser entregue, retorna o status 2:

image14.png

E ao ser lida, retorna o status 3:

image23.png

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

image35.png

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

image15.png

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:

image1.png

 


 

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:

image22.png

Dentro do conversor, vamos colar dentro de input base64:

image29.png
Ficará desta forma, já com a imagem formatada:

image13.png

É possível salvar e utilizar a imagem recebida:

image9.jpg