Webhooks do WhatsApp: encaminhe mensagens diretamente para o seu servidor
Um webhook do WhatsApp é um endpoint HTTPS que indica, e a Meta publica nele eventos como mensagens recebidas, estados de entrega, alterações de qualidade e atualizações da conta. Num número Coexistence, o destino pode ser o seu próprio servidor, para que as conversas nunca passem por um fornecedor.
- A Meta publica eventos diretamente no seu URL
- O seu endpoint, não a plataforma de um fornecedor
- Um override por WhatsApp Business Account
Nada é cobrado durante 7 dias. Cancele quando quiser.
O que é a integração completa: um destino HTTPS por conta.
messages e smb_message_echoes, os eventos do percurso das mensagens encaminhados para si.
O valor que a Meta envia no handshake GET e que o seu endpoint tem de devolver.
O que envia realmente a Meta para um webhook?
Eventos organizados por categorias, cuja distinção determina a sua arquitetura.
O percurso das mensagens transporta o que os clientes enviam e, num número Coexistence, cópias do que a sua equipa envia na aplicação WhatsApp Business. Esses campos são messages e smb_message_echoes, os únicos que contêm conteúdo das conversas.
O percurso operacional transporta tudo o resto: account_update quando muda o estado de uma ligação, phone_number_quality_update quando muda a qualidade ou o throughput, account_alerts, account_review_update, business_capability_update e phone_number_name_update. Estes eventos não contêm conteúdo das conversas e são a base da monitorização.
Um fornecedor que se coloca no percurso das mensagens recebe o primeiro grupo. Um que não o faça, não o recebe.
Como verifica a Meta um endpoint?
Com um pedido GET antes de entregar qualquer conteúdo. Falhar esta etapa é a razão mais comum para uma configuração aparentemente concluída nunca receber uma mensagem.
A Meta chama o seu URL com hub.mode definido como subscribe, o seu hub.verify_token e um valor hub.challenge. O seu endpoint tem de devolver esse challenge no corpo da resposta, sem o envolver em JSON nem acrescentar nada. Se não o fizer, a Meta nunca começa a entregar eventos e nenhum painel o indicará.
O endpoint também tem de usar HTTPS. Um endpoint que devolve um 404 silencioso, ou que está atrás de uma camada de autenticação que rejeita a Meta, parece funcionar até a primeira mensagem nunca chegar.
O destino pode apontar para o seu próprio servidor?
Sim, e é aqui que os fornecedores diferem.
A Meta permite a uma aplicação substituir o destino dos webhooks de uma determinada WhatsApp Business Account. Definimos esse override para o seu URL, transferindo para si os eventos do percurso das mensagens que iriam para o nosso callback. Mantemos os eventos operacionais, porque o painel e os alertas são construídos a partir deles.
A consequência é arquitetural, não uma política que publiquemos. O conteúdo das conversas não tem onde ser armazenado do nosso lado, porque nunca nos é entregue. Uma conta sem override usa o nosso callback predefinido, onde o handler elimina esses eventos sem os guardar.
O que acontece ao destino quando um número volta a ligar-se?
É removido, uma falha para a qual quase ninguém se prepara.
O destino não é uma propriedade do número de telefone. É um override na subscrição da nossa aplicação à WhatsApp Business Account. Quando uma ligação é removida, pela regra de catorze dias de inatividade da Meta ou por outro motivo, a aplicação é desinstalada dessa conta e o override desaparece com ela.
Voltar a ligar restaura o envio e a monitorização. Não restaura a entrega para o seu servidor e nada comunica um erro, pelo que o primeiro sinal pode ser um cliente dizer que ninguém respondeu. Voltamos a aplicar o override em cada reconexão, porque isto aconteceu com um número real que voltou a ligar-se sem problemas e ficou silencioso.
Erros comuns
- Devolver JSON no GET de verificação. A Meta quer o valor bruto de hub.challenge e mais nada.
- Usar um URL temporário ou de teste. A Meta continua a entregar-lhe eventos depois de a ferramenta que o gerou deixar de escutar.
- Partir do princípio de que o destino sobrevive a uma reconexão. Está associado a uma subscrição de aplicação e é desinstalado com ela.
- Colocar o endpoint atrás de uma autenticação que rejeita o pedido da Meta.
A EasyCoexistence define o override do webhook para o seu endpoint, valida-o antes da chamada e volta a aplicá-lo automaticamente após qualquer reconexão. A partir de US$ 9 por número por mês, descendo para US$ 2 em volume, com os primeiros 7 dias gratuitos.
Perguntas frequentes
As minhas mensagens passam pela EasyCoexistence?
Não. O override envia os eventos do percurso das mensagens diretamente da Meta para o seu endpoint. Os eventos de uma conta sem override usam o nosso callback e são eliminados sem serem guardados.
Posso alterar o destino mais tarde?
Sim, a qualquer momento, no painel ou através do conector MCP. Passar null repõe o destino predefinido.
O que acontece se o meu servidor estiver indisponível quando a Meta entregar os eventos?
A Meta tenta novamente durante algum tempo e depois para. As mensagens continuam a chegar à aplicação WhatsApp Business no telemóvel, pelo que a empresa não perde nada, mesmo quando a integração falha.
Um webhook chega para vários números?
Sim. Aponte todos os números para o mesmo endpoint e ramifique pelo phone number id que recebe no payload.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoNada é cobrado durante 7 dias. Cancele quando quiser.Verificado em