Webhook
Webhooks são retornos de chamada de HTTP definidos pelo usuário que são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, o cliente da API do WhatsApp Business verá o evento, coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) ao URL do WhatsApp especificado nas configurações do aplicativo atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem.É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações. Caso contrário, o cliente da API do WhatsApp Business considerará essa notificação uma falha e tentará novamente após um atraso.
Configuração do Webhook
Para receber notificações, o cliente precisa cadastrar a URL do seu Webhook no número. Definir/atualizar a URL do Webhook:webhook é opcional (pode ser null para remover) e tem no máximo 255 caracteres. Se a URL do Webhook não estiver definida, as notificações não serão entregues.
Se sua URL de Webhook fica atrás de um firewall ou lista de permissões, libere os IPs de origem da Positus. Consulte IPs para liberação de Webhook.
Além do Webhook principal, é possível configurar um webhook secundário (
secondary_webhook). Quando definido, ele recebe as mesmas notificações que o Webhook principal."Beep Beep!") para a URL configurada:
É importante que seu Webhook retorne uma resposta HTTP 200 OK às notificações. Caso contrário, a notificação será considerada uma falha e haverá tentativas de reenvio.
Definir configurações de notificações
Os números da Positus utilizam a WhatsApp Cloud API. O cliente recebe, na URL de Webhook cadastrada, um subconjunto normalizado do payload da Meta (sem o envelopeentry/changes). Os objetos entregues são os objetos crus da Cloud API.
Sempre que possível, os nomes serão mantidos constantes nas funções. (Por exemplo, todos os registros de data e hora são denominados
timestamp.Novos identificadores de usuário (BSUID). Com a chegada dos usernames do WhatsApp, os payloads de webhook passam a trazer campos adicionais de identificação —
user_id (BSUID), parent_user_id (parent BSUID) e profile.username. Quando o usuário adota um username, os campos de telefone (wa_id, from, recipient_id) podem ser omitidos do payload. Trate esse cenário usando o user_id como identificador principal. Para entender esses identificadores, consulte a página BSUID e identificadores de usuário.Formato do Webhook de notificações
Uma notificação de mensagem recebida tem o topo{ "contacts": [...], "messages": [...] }. Uma notificação de status tem o topo { "statuses": [...], "contacts": [...] } (o contacts só está presente quando o status não é failed).
Exemplo (mensagem de texto recebida)
Os campos
profile.username, user_id e parent_user_id só aparecem nos cenários descritos na página BSUID. O wa_id (e o from da mensagem) podem ser omitidos quando o usuário adotou um username. Os campos abaixo são acrescidos ao objeto contacts[] (não substituem os já existentes):O campo
messages[].from (telefone do remetente) segue o mesmo comportamento do wa_id: pode não vir quando o usuário adotou um username. Use o user_id presente no objeto contacts[] correspondente para identificar o remetente de forma durável.Atualizações de status das mensagens
Além das mensagens recebidas, o cliente recebe notificações de status das mensagens que enviou. Essas notificações têm o topo{ "statuses": [...], "contacts": [...] }.
Exemplo (status delivered)
O array
contacts que acompanha o status (quando presente) traz os mesmos campos BSUID descritos em mensagens recebidas: user_id, parent_user_id e profile.username.
O campo status pode assumir os seguintes valores:
Quando o
status é failed, o objeto de status inclui uma matriz errors com o detalhe da falha e o contacts não é enviado.
Exemplo (status failed)
Erros de notificações
Quando houver erros fora da banda que ocorrerem na operação normal do aplicativo, a matrizerrors fornecerá uma descrição do erro. Esse tipo de erro pode ser provocado por erros de conectividade de rede temporários, credenciais inválidas, controladores de gerenciamento com status indisponível e assim por diante. Se você receber um erro, consulte Mensagens de erro e status para obter mais informações.
Exemplo
O objeto
errors contém os seguintes parâmetros:
Notificações de mensagens de entrada
Você recebe uma notificação quando sua empresa recebe uma mensagem. A seção do objetomessages apresenta todas as informações que podem ser recebidas sobre uma mensagem de entrada.
Exemplo: Mensagem recebida Text
Exemplo: Mensagem de localização estática recebida
Exemplo: Mensagem com contatos recebida
Mensagem de sistema: usuário mudou de identificador (user_changed_user_id)
Quando o identificador de um usuário muda (por exemplo, ao trocar de número), o WhatsApp envia uma mensagem de sistema do tipo system com system.type igual a user_changed_user_id. Ela chega dentro do array messages, no mesmo formato das demais mensagens recebidas. Use-a para atualizar o vínculo do contato com o novo user_id.
Notificações de mensagens de mídia de entrada
Quando uma mensagem com mídia é recebida, a notificação enviada ao seu Webhook contém um objeto de mídia com os campos que identificam o arquivo. Na Cloud API, o objeto de mídia traz apenasid, mime_type e sha256 (mais caption opcional para imagem, documento e vídeo). Não há campos file nem link.
Para baixar a mídia, use o id no endpoint de download: GET https://api.positus.global/v2/whatsapp/numbers/{chave}/media/{id}.
Exemplo: Mensagem com imagem recebida
Exemplo: Mensagem com documento recebida
Exemplo: Mensagem com áudio recebida
Na Cloud API, mensagens de áudio (incluindo mensagens de voz) são entregues com o tipo
audio, não voice.Exemplo: Mensagem com vídeo recebida
Exemplo: Mensagem com figurinha recebida
Respostas de entrada a mensagens enviadas
Os usuários podem responder a uma mensagem específica no WhatsApp. Para que a empresa entenda o contexto da resposta a uma mensagem, incluímos o objetocontext. Esse objeto context fornece o id da mensagem à qual o cliente respondeu e o ID do WhatsApp do remetente da mensagem original.
Exemplo: Cliente respondeu à sua mensagem
Webhooks de eventos do workspace (BSUID)
Além das notificações de mensagens e status (entregues no formato cru da Cloud API), a Positus envia dois eventos de workspace relacionados ao BSUID. Esses eventos usam um envelope diferente: um objeto de topo com o campoevent (nome do evento), o objeto workspace (identificação do workspace) e um objeto com os dados do evento — nomeado contact ou number, conforme o caso.
Atualização de BSUID (user_id_update)
Disparado quando o BSUID (ou parent BSUID) de um usuário é atualizado. Traz os valores anterior e atual de cada identificador. Os dados vêm no objeto contact.
Atualização de username da linha (business_username_update)
Disparado quando muda o status do username da sua linha oficial (o @nome público do número comercial). Os dados vêm no objeto number.
Documentação oficial WhatsApp Cloud API
A Positus utiliza a WhatsApp Cloud API e entrega os objetos no mesmo formato do padrão oficial da Meta. A documentação completa e atualizada pode ser encontrada no link abaixo:https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components