Webhooks do WhatsApp: mensagens direto no seu servidor

O que a Meta manda de fato para um webhook?

Eventos, em categorias, e a distinção entre elas decide sua arquitetura.

O caminho de mensagem carrega o que os clientes enviam e, num número em Coexistência, ecos do que sua equipe envia pelo app do WhatsApp Business. São os campos messages e smb_message_echoes, e são os que contêm conteúdo de conversa.

O caminho operacional carrega todo o resto: account_update quando um estado de conexão muda, phone_number_quality_update quando qualidade ou throughput se move, account_alerts, account_review_update, business_capability_update e phone_number_name_update. Esses não contêm conteúdo de conversa e são do que o monitoramento é feito.

Um provedor que se coloca no caminho de mensagem recebe o primeiro grupo. Um que não se coloca, não recebe.

Como a Meta verifica um endpoint?

Com uma requisição GET antes de entregar qualquer coisa, e falhar nisso é o motivo mais comum de uma configuração que parece pronta nunca receber mensagem.

A Meta chama sua URL com hub.mode valendo subscribe, seu hub.verify_token, e um valor hub.challenge. Seu endpoint precisa devolver aquele challenge como corpo bruto da resposta, não embrulhado em JSON e sem nada acrescentado. Se não devolver, a Meta nunca começa a entregar, e nenhum painel vai avisar.

O endpoint também precisa ser HTTPS. Um endpoint que devolve 404 em silêncio, ou um atrás de uma camada de autenticação que rejeita a Meta, parece idêntico a uma configuração funcionando até a primeira mensagem não chegar.

O destino pode apontar para o seu próprio servidor?

Pode, e é essa a parte que difere entre provedores.

A Meta permite que um app sobrescreva onde uma dada conta do WhatsApp Business entrega os webhooks. Nós apontamos esse override para a sua URL, o que move os eventos do caminho de mensagem do nosso callback para o seu. Ficamos com os eventos operacionais, porque o painel e os alertas são feitos deles.

A consequência é arquitetural, não uma política que a gente publica. Conteúdo de conversa não tem onde ser armazenado do nosso lado, porque nunca é entregue a nós. Uma conta sem override cai no nosso callback padrão, onde o handler descarta esses eventos sem persistir.

O que acontece com o destino quando um número reconecta?

Ele é removido, e essa é a falha que quase ninguém planeja.

O destino não é propriedade do número de telefone. É um override na assinatura do nosso app à conta do WhatsApp Business. Quando uma conexão é removida, pela regra de quatorze dias de inatividade da Meta ou por outro motivo, o app é desinstalado daquela conta e o override vai junto.

Reconectar restaura o envio e restaura o monitoramento. Não restaura a entrega no seu servidor, e nada reporta erro, então o primeiro sinal é um cliente dizendo que ninguém respondeu. Nós reaplicamos o override em toda reconexão, porque isso aconteceu com um número real que reconectou limpo e ficou mudo.

Erros comuns

• Devolver JSON no GET de verificação. A Meta quer o valor bruto de hub.challenge e nada mais.
• Usar uma URL temporária ou de teste. A Meta continua entregando nela depois que a ferramenta que a gerou para de escutar.
• Achar que o destino sobrevive a uma reconexão. Ele vive numa assinatura de app e é desinstalado junto.
• Colocar o endpoint atrás de autenticação que rejeita a requisição da Meta.

Perguntas frequentes

Continue lendo