node | Enviar e receber WhatsApp a partir do Node.js
Receber é uma rota que responde ao GET de verificação da Meta e aceita POSTs. Enviar é uma chamada fetch para a Cloud API com o phone number id e o token do número. Não existe SDK nosso e não há nada para instalar.
Um GET para a verificação da Meta e um POST para os eventos.
Janela depois da mensagem do cliente em que o texto livre é enviado.
O erro devolvido quando você envia texto livre fora dessa janela.
Como receber mensagens em Node?
Uma rota com dois métodos, em Express, Fastify, num route handler do Next ou num servidor puro.
O GET responde à verificação da Meta: leia hub.mode, hub.verify_token e hub.challenge da query, compare o token com o seu, e devolva o challenge como texto puro. Devolver como JSON é o erro de sempre e produz um endpoint que nunca recebe nada enquanto parece estar correto.
O POST recebe os eventos. Responda 200 imediatamente e processe depois. A Meta repete qualquer coisa lenta, e um handler que faz o trabalho antes de responder vai ver a mesma mensagem mais de uma vez. Em serverless, em especial, responder primeiro e enfileirar o trabalho é o que impede que um cold start vire uma duplicata.
Como enviar?
Um fetch para o endpoint de mensagens da Cloud API do phone number id, com o token no header bearer.
Nada nisso é específico nosso, então a requisição bate exatamente com a documentação da própria Meta e não há wrapper para aprender nem para ficar preso. Os dois valores estão no painel, e o get_api_credentials devolve eles pelo conector MCP se for um assistente fazendo a ligação.
O corpo depende do tempo. Dentro de 24 horas da última mensagem recebida do cliente, envie um objeto de texto. Fora disso, envie um objeto de template com um nome de template aprovado e o idioma. Código que só envia texto passa em todos os testes e falha na primeira mensagem que chega de madrugada.
O que muda em serverless?
Duas coisas, e as duas são sobre a função terminar antes do trabalho terminar.
Devolver 200 e depois seguir processando não sobrevive a uma função que congela no instante em que responde. Use o que a sua plataforma oferecer para manter o trabalho vivo depois da resposta, ou empurre o payload para uma fila e deixe outra função tratar. A Meta só precisa do reconhecimento rápido; ela não precisa que o trabalho esteja feito.
Cold starts também tornam respostas lentas mais prováveis, o que significa mais repetições e mais duplicatas. Deduplicar pelo id de mensagem wamid não é opcional neste formato, é justamente o que o torna confiável.
Erros comuns
- Devolver o challenge como JSON em vez de como corpo bruto.
- Fazer o trabalho antes de responder 200. Em serverless a função pode congelar no instante em que responde.
- Pular a deduplicação. A Meta repete por projeto e duplicatas são normais, não um caso de borda.
Conecte o número em easycoexistence.com, defina o destino do webhook como a sua rota, e leia o phone number id e o token no painel. A partir de R$ 29,90 por número por mês, caindo para R$ 7,90 no volume, com os primeiros 7 dias gratuitos.
Perguntas frequentes
Preciso de uma biblioteca?
Não. Uma rota e o fetch bastam, e a chamada bate exatamente com a documentação da Meta.
Isso funciona na Vercel ou no Lambda?
Sim, com a ressalva de sempre do serverless: reconheça primeiro, depois processe por uma fila ou por um mecanismo em segundo plano, em vez de ali mesmo.
Como verifico que a requisição veio da Meta?
Confira o header de assinatura contra o app secret. Vale fazer assim que o endpoint ficar público.
Posso usar TypeScript?
Pode. Não há nada nosso contra o que tipar, já que o payload é da Meta e documentado pela Meta.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em