Enviar e receber WhatsApp a partir de Node.js
Receber consiste numa rota que responde ao GET de verificação da Meta e aceita POSTs. Enviar consiste numa chamada fetch à Cloud API com o phone number id e o token do número. Não existe um SDK nosso nem nada para instalar.
Um GET para a verificação da Meta e um POST para eventos.
A janela após uma mensagem do cliente em que pode enviar texto livre.
O erro devolvido quando envia texto livre fora dessa janela.
Como recebe mensagens no Node?
Uma rota com dois métodos, em Express, Fastify, num route handler do Next ou num servidor simples.
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 simples. Devolvê-lo como JSON é o erro habitual e cria um endpoint que nunca recebe nada, embora pareça correcto.
O POST recebe eventos. Responda imediatamente com 200 e processe depois. A Meta repete tudo o que demora, e um handler que processa antes de responder verá a mesma mensagem mais de uma vez. Sobretudo em serverless, responder primeiro e colocar o trabalho numa fila impede que um arranque a frio gere um duplicado.
Como envia?
Um fetch para o endpoint messages da Cloud API, usando o phone number id, com o token num cabeçalho bearer.
Nada é específico da nossa solução, por isso o pedido corresponde exactamente à documentação da Meta e não existe nenhum wrapper para aprender ou ao qual ficar preso. Ambos os valores estão no painel, e get_api_credentials devolve-os através do conector MCP quando um assistente está a configurar a integração.
O corpo depende do momento. Nas 24 horas seguintes à última mensagem recebida do cliente, envie um objecto de texto. Depois disso, envie um objecto template com um nome de template aprovado e o idioma. O código que só envia texto passa todos os testes e falha na primeira mensagem que chega durante a noite.
O que muda em serverless?
Há duas coisas, ambas relacionadas com a função terminar antes de o trabalho estar concluído.
Responder com 200 e continuar a processar não funciona numa função que congela no momento em que responde. Use o mecanismo da sua plataforma que mantém o trabalho activo depois da resposta, ou coloque o payload numa fila e deixe outra função tratá-lo. A Meta só precisa da confirmação rapidamente, não precisa que o trabalho esteja concluído.
Os arranques a frio também tornam as respostas lentas mais prováveis, o que significa mais repetições e mais duplicados. Deduplicar pelo ID de mensagem wamid não é opcional neste modelo, é o que o torna fiável.
Erros comuns
- Devolver o challenge como JSON em vez de no corpo bruto.
- Fazer o trabalho antes de responder com 200. Em serverless, a função pode congelar no momento em que responde.
- Ignorar a deduplicação. A Meta repete por definição e os duplicados são normais, não uma situação excepcional.
Ligue o número em easycoexistence.com, defina o destino do webhook para a sua rota e leia o phone number id e o token no painel. A partir de US$ 9 por número por mês, descendo para US$ 2 em volume, com os primeiros 7 dias grátis.
Perguntas frequentes
Preciso de uma biblioteca?
Não. Uma rota e um fetch são suficientes, e a chamada corresponde exactamente à documentação da Meta.
Funciona na Vercel ou no Lambda?
Sim, com a habitual ressalva de serverless: confirme primeiro e processe depois através de uma fila ou mecanismo em segundo plano, em vez de o fazer inline.
Como verifico que o pedido veio da Meta?
Verifique o cabeçalho da assinatura com o segredo da sua aplicação. Vale a pena fazê-lo assim que o endpoint estiver público.
Posso usar TypeScript?
Sim. Não há nada para tipar da nossa parte, porque o payload é da Meta e está documentado por ela.
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 gratuitoVerificado em