---
title: "Cursor, Claude Code e Copilot: a integração de WhatsApp certa na 1ª tentativa"
description: "O modelo não erra por burrice: erra por falta de contexto. O checklist do que dar ao editor, o que pedir antes do código e os três enganos que ele repete todo dia."
url: "https://wame.api.br/blog/cursor-claude-code-integrar-whatsapp"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-23"
modified_time: "2026-09-23"
author: "Raphael Serafim"
keywords: "cursor ia, claude code, github copilot, llms txt, integrar whatsapp no crm, api whatsapp, vibecoding"
reading_time: "9 min de leitura"
---

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

> O modelo não erra por burrice: erra por falta de contexto. O checklist do que dar ao editor, o que pedir antes do código e os três enganos que ele repete todo dia.

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://wame.api.br/llms.txt`](https://wame.api.br/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://wame.api.br/llms-full.txt` com a referência completa e `https://server.wame.api.br/docs/swagger.json` com o OpenAPI. O artigo [Cole este link na sua IA e ela integra o WhatsApp](/blog/llms-txt-ensinar-whatsapp-para-sua-ia) 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](/blog/templates-whatsapp-api-criar-aprovar-enviar).

### 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](/blog/webhook-producao-assinatura-retry-idempotencia).

## 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](/blog/mcp-agente-ia-whatsapp) 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://wame.api.br/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.

## Perguntas frequentes

### Qual assistente funciona melhor para integrar WhatsApp?

A diferença entre os principais é menor que a diferença entre ter e não ter a documentação certa em contexto. Prefira o que aceitar buscar uma URL e manter arquivos de regra do projeto, porque são esses dois recursos que carregam o resultado — o modelo em si importa menos do que parece aqui.

### Preciso colar a documentação toda vez que abro o editor?

Depende da ferramenta. Ambientes que suportam arquivos de instrução do projeto guardam isso uma vez e aplicam sempre; nos demais, vale repetir o link no começo de cada sessão e de novo quando a conversa ficar longa, porque instruções antigas perdem peso conforme o contexto cresce.

### Por que a IA insiste em me dar código com QR code e sessão em disco?

Porque a maior parte do material de WhatsApp em Node na internet é de bibliotecas não oficiais que funcionam assim. Numa API HTTP gerenciada não há sessão, QR nem navegador — dizer isso explicitamente na primeira instrução corta o problema antes de ele aparecer.

### Vale pedir testes ao assistente?

Vale, e especialmente para os três enganos deste artigo: um teste que manda o mesmo webhook duas vezes, um que tenta enviar com a janela vencida e um que recebe os status fora de ordem. São exatamente os casos que não aparecem no teste feliz e aparecem na conta do primeiro cliente.

### O assistente consegue resolver a parte da conta na Meta?

Não, e vale não esperar isso dele. Criar Business Manager, passar pela verificação de negócio, liberar o número e aprovar template são etapas com prazo de terceiro; o que dá para fazer é começá-las no primeiro dia do projeto, em vez de no último.