--- title: "Cursor, Claude Code e Copilot: integrar WhatsApp" 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://api-wa.me/blog/cursor-claude-code-integrar-whatsapp" language: "pt-BR" og:type: "article" og:site_name: "WAME API" --- [Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Cursor, Claude Code e Copilot: a integração de WhatsApp certa na 1ª tentativa Raphael Serafim· Publicado em 23 de setembro de 2026· 9 min de leitura Compartilhar # 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. Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/cursor-claude-code-integrar-whatsapp.md) 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`](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](https://api-wa.me/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: Copiar ``` 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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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://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. ### Pronto para automatizar seu WhatsApp? Crie sua conta gratuita e comece a enviar mensagens pela API em minutos. [Começar grátis](https://portal.api-wa.me/sign-up) ## 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. ## Continue lendo [### Cole este link na sua IA e ela integra o WhatsApp: o que é um llms.txt Documentação em HTML confunde o modelo. Um llms.txt é a mesma API em Markdown, pensada para caber no contexto — e é a diferença entre código que roda e código bonito.](https://api-wa.me/blog/llms-txt-ensinar-whatsapp-para-sua-ia)[### Como criar um CRM do zero com IA A IA entrega modelo de dados, funil e painel em dias. Ela não entrega canal, entrega de mensagem nem multi-inquilino. O que fazer com cada uma das três partes.](https://api-wa.me/blog/criar-crm-com-ia-o-que-a-ia-nao-resolve)[### Fiz meu CRM num fim de semana com IA. Aí chegou o WhatsApp. Sábado: CRUD, funil e login prontos. Domingo: o WhatsApp. A parede tem nomes — Business Manager, verificação, template, janela de 24 horas — e este é o mapa dela.](https://api-wa.me/blog/crm-em-um-fim-de-semana-e-ai-chegou-o-whatsapp) [Voltar ao blog](https://api-wa.me/blog) ## Structured data ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "WAME API", "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram, Messenger e Telegram", "url": "https://api-wa.me", "inLanguage": "pt-BR", "publisher": { "@id": "https://api-wa.me/#organization", "@type": "Organization", "name": "WAME API", "url": "https://api-wa.me" } } { "@context": "https://schema.org", "@type": "Organization", "@id": "https://api-wa.me/#organization", "name": "WAME API", "alternateName": [ "WAME", "Wame API", "wame.api.br", "api-wa.me" ], "url": "https://api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/web-app-manifest-512x512.png", "width": 512, "height": 512 }, "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.", "identifier": { "@type": "PropertyValue", "propertyID": "INPI-BR", "name": "Pedido de registro de marca (INPI, classe NCL 42)", "value": "944724159" }, "foundingDate": "2017", "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram, Messenger e Telegram numa instância só. Desde 2017.", "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code e o Telegram, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.", "knowsAbout": [ "WhatsApp Cloud API oficial (Meta)", "API oficial de Instagram (Direct)", "API oficial de Messenger", "API multicanal Meta", "Meta Business Partner", "WhatsApp API", "API não oficial de WhatsApp", "automação de WhatsApp", "números virtuais", "webhooks" ], "sameAs": [ "https://github.com/wame-api", "https://www.linkedin.com/company/wameapi", "https://www.instagram.com/wame.api/", "https://www.youtube.com/@wameapi" ], "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://api-wa.me/contact", "availableLanguage": [ "Portuguese" ] } } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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.", "image": "https://api-wa.me/blog/cursor-claude-code-integrar-whatsapp/opengraph-image", "datePublished": "2026-09-23", "dateModified": "2026-09-23", "author": { "@type": "Person", "name": "Raphael Serafim", "url": "https://github.com/raphaelvserafim", "sameAs": [ "https://github.com/raphaelvserafim" ] }, "publisher": { "@type": "Organization", "name": "api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/screenshot.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://api-wa.me/blog/cursor-claude-code-integrar-whatsapp" }, "keywords": "cursor ia, claude code, github copilot, llms txt, integrar whatsapp no crm, api whatsapp, vibecoding", "inLanguage": "pt-BR" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://api-wa.me" }, { "@type": "ListItem", "position": 2, "name": "Blog da API do WhatsApp", "item": "https://api-wa.me/blog" }, { "@type": "ListItem", "position": 3, "name": "Cursor, Claude Code e Copilot: a integração de WhatsApp certa na 1ª tentativa", "item": "https://api-wa.me/blog/cursor-claude-code-integrar-whatsapp" } ] } { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Qual assistente funciona melhor para integrar WhatsApp?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Preciso colar a documentação toda vez que abro o editor?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Por que a IA insiste em me dar código com QR code e sessão em disco?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Vale pedir testes ao assistente?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "O assistente consegue resolver a parte da conta na Meta?", "acceptedAnswer": { "@type": "Answer", "text": "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." } } ] } ```