Cursor, Claude Code e Copilot: a integração de WhatsApp certa na 1ª tentativa

Você digita "integra o WhatsApp aqui" e recebe um arquivo completo em quinze segundos. Cliente HTTP, função de envio, endpoint de webhook, tratamento de erro, tudo tipado. Você lê, aprova, roda. E toma 404 numa URL que parecia perfeitamente razoável.

Isso não é o assistente falhando. É o assistente fazendo exatamente o que você pediu com o material que você deu — que foi nenhum. Este artigo é o checklist de como não repetir isso: o que colocar no contexto antes de pedir código, em que ordem pedir, e os três enganos específicos dessa integração que aparecem de novo e de novo.

Por que o modelo erra justo aqui

Três razões se somam, e nenhuma tem conserto do lado dele.

A documentação da Meta mudou várias vezes. O caminho da Cloud API tem número de versão, os nomes de alguns campos mudaram, e recursos inteiros foram substituídos. O modelo viu todas as versões no treino, sem data em nenhuma. Ele devolve a média, e a média não corresponde a nenhuma versão real.

Metade do material de treino é biblioteca não oficial. Há muito mais tutorial de Baileys e de wrappers comunitários na internet do que de qualquer API gerenciada. O modelo aprendeu que "mandar WhatsApp em Node" começa com um QR code e uma sessão em disco, então ele escreve isso — mesmo quando você está usando uma API HTTP onde nada daquilo existe.

O que mais importa não é código. A janela de 24 horas, o template aprovado, a reentrega de webhook: nenhuma dessas regras aparece numa assinatura de função. Elas são regras de produto que se manifestam no modelo de dados e na tela. O modelo só as leva em conta se estiverem escritas na documentação que ele leu naquela sessão.

O checklist: o que dar antes de pedir qualquer coisa

1. A documentação da API que você vai usar, em Markdown

Esta é a de maior efeito por unidade de esforço. Cole https://api-wa.me/llms.txt no contexto e a natureza das respostas muda na mesma hora — os endpoints passam a existir.

Precisando de detalhe de campo, há dois níveis abaixo: https://api-wa.me/llms-full.txt com a referência completa e https://us.api-wa.me/docs/swagger.json com o OpenAPI. O artigo Cole este link na sua IA e ela integra o WhatsApp explica o que é cada um e quando usar.

2. O seu modelo de dados atual

Mande o arquivo de schema, a migração, a entidade — o que existir. Sem isso, o assistente inventa tabelas paralelas: você já tem clientes e ele cria contacts; você já tem atendimentos e ele cria conversations. Depois alguém passa uma semana costurando as duas metades.

3. As regras do canal, escritas como restrição

Não confie em ele deduzir da documentação. Escreva:

Restrições que valem para todo código desta integração:

- Janela de 24h: só respondo com texto livre em até 24 horas desde a
  última mensagem do cliente. Fora disso, iniciar conversa exige
  template aprovado pela Meta.
- O webhook pode ser reentregue. Ingestão precisa ser idempotente pelo
  id externo da mensagem.
- Status de entrega chega fora de ordem. O status só pode avançar
  (sent → delivered → read); "failed" é terminal.
- Não guarde arquivo de mídia. Faça proxy sob autenticação.

Quatro linhas que economizam quatro incidentes.

4. O padrão de erro do seu projeto

Se você já tem um jeito de tratar falha de serviço externo, mostre um exemplo. Do contrário, o assistente escreve um try/catch que engole tudo e devolve null — e você descobre isso quando uma mensagem não chegar e não houver nada no log.

A ordem de pedir importa mais que o prompt

O erro de processo mais comum é pedir o arquivo pronto. Um arquivo de 200 linhas obriga você a auditar 200 linhas, e ninguém audita 200 linhas com a mesma atenção que audita 10.

A sequência que funciona tem quatro passos:

Primeiro, o plano. "Liste os endpoints que você vai chamar, os campos de cada um e onde a janela de 24h entra no meu modelo de dados. Não escreva código ainda." A saída é uma lista que você confere em dois minutos. Endpoint errado aparece aqui, antes de virar código, teste e commit.

Segundo, o modelo de dados. Peça as mudanças de schema separadas do resto. É a parte mais cara de corrigir depois, porque ela arrasta migração e tela junto.

Terceiro, o envio. Uma função, uma responsabilidade. Rode contra o seu próprio número antes de seguir. Se a primeira mensagem chega, metade do risco acabou.

Quarto, o recebimento. O webhook por último, porque ele depende de endereço público e de configuração do lado de lá. E peça a idempotência junto, não depois: acrescentar deduplicação num ingestor pronto costuma virar reescrita.

Os três enganos que ele repete todo dia

Engano 1: o endpoint que não existe

Sintoma: 404, ou uma resposta de HTML onde você esperava JSON. Causa: o modelo compôs uma URL a partir de fragmentos de várias versões da documentação da Meta.

Defesa: nunca aceite endpoint que você não viu na documentação atual. Uma instrução resolve — "não use nenhum endpoint que não esteja nos arquivos que eu passei; se não estiver lá, pergunte" — e vale repeti-la quando a conversa ficar longa, porque instrução do começo perde peso conforme o contexto cresce.

Engano 2: a janela de 24 horas simplesmente não existe

Sintoma: a caixa de digitação funciona nos seus testes e é recusada em produção, com um erro que fala de "template" e não explica nada. Causa: o modelo escreveu um envio que sempre manda texto livre, porque é isso que todo exemplo de tutorial faz.

Defesa: a janela é um campo na conversa, não um if no envio. Cada mensagem recebida atualiza a data de expiração; a tela lê esse campo para decidir entre a caixa de digitação e a lista de templates. Peça isso explicitamente, no passo do modelo de dados. O funcionamento dos templates — criação, aprovação e disparo — está em Templates do WhatsApp pela API.

Engano 3: o webhook como se chegasse uma vez só

Sintoma: mensagem duplicada na tela do atendente, e sempre em produção, nunca no teste. Causa: o código lê o corpo e faz insert, porque nos testes cada evento chega exatamente uma vez.

Defesa: índice único no id externo da mensagem, e reentrega descartada em silêncio. Vale pedir também que o endpoint responda 200 antes de processar — segurar a resposta faz o remetente marcar o seu endereço como lento e reentregar mais ainda, o que piora justamente o problema que você está tentando resolver. O detalhe de assinatura, reentrega e idempotência está em Webhook em produção.

Isto não é o mesmo que ligar a IA ao WhatsApp

Vale separar, porque os dois assuntos usam as mesmas palavras e resolvem problemas opostos.

Aqui, a IA é ferramenta de quem escreve o sistema. O produto do trabalho é código no seu repositório, que depois roda sozinho, sem nenhum modelo envolvido.

O outro assunto é a IA dentro da conversa: um agente que lê o que o cliente escreveu, responde, consulta o seu sistema e escala para um humano quando precisa. Isso é tempo de execução, custa token por conversa e tem outro conjunto de problemas — o artigo sobre MCP na prática cobre o caminho de dar ferramentas de WhatsApp a um agente, e ele não substitui nada do que está aqui.

A confusão é cara de um jeito específico: quem acha que são a mesma coisa termina com um agente respondendo clientes antes de ter uma integração confiável por baixo. O agente parece funcionar, e as mensagens duplicadas ficam por conta da idempotência que ninguém escreveu.

O que revisar antes de aceitar o código

Cinco perguntas, na ordem em que custam caro:

1. Cada endpoint aqui existe na documentação? Confira um por um contra o arquivo que você colou. Leva um minuto.
2. Onde está guardado o prazo da janela de 24 horas? Se a resposta for "em lugar nenhum", volte ao modelo de dados.
3. O que acontece se este webhook chegar duas vezes? Se a resposta não for "nada", falta o índice único.
4. A chave está no ambiente? O modelo escreve credencial no arquivo com uma frequência desconfortável, especialmente em exemplos.
5. O erro chega a algum lugar? catch que devolve null é a forma mais eficiente de transformar um problema de dez minutos num problema de dois dias.

Nenhuma dessas exige ler o código inteiro. São cinco buscas.

O que continua sendo seu, e não do assistente

Vale terminar com a parte que nenhum contexto resolve.

Conta na Meta, verificação de negócio, número liberado do aplicativo e template aprovado não são programação: são conta, documento e espera. O assistente pode listar os passos, mas o prazo não é dele nem seu. Quem descobre isso depois de o sistema estar pronto perde a semana seguinte; quem descobre antes reorganiza a ordem do projeto e não perde nada.

A escolha de arquitetura também continua sendo sua. O modelo aceita qualquer desenho que você propuser e escreve código bom para um desenho ruim — com convicção e comentários. Ele é excelente executando uma decisão e péssimo tomando uma.

Conclusão

A diferença entre um arquivo bonito que não roda e um arquivo simples que roda não está no modelo, no editor nem no tamanho do prompt. Está em três coisas: a documentação atual no contexto, as regras do canal escritas como restrição, e o hábito de pedir o plano antes do código.

Comece pela documentação, porque é o de menor esforço e maior efeito: cole https://api-wa.me/llms.txt, peça a lista de endpoints, confira a lista. Depois disso, o assistente volta a ser o que ele é de melhor — alguém que escreve rápido uma coisa que você já sabe que está certa.