---
title: "Vibecoding até o primeiro cliente: o que quebra"
description: "Webhook reentregue, status fora de ordem, janela fechando de madrugada e mídia que você não devia guardar. Seis defeitos com sintoma, causa e defesa."
url: "https://api-wa.me/blog/vibecoding-primeiro-cliente-o-que-quebra"
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)/Vibecoding até o primeiro cliente: o que quebra fora da sua máquina

Raphael Serafim· Publicado em 23 de setembro de 2026· 9 min de leitura

Compartilhar

# Vibecoding até o primeiro cliente: o que quebra fora da sua máquina

Webhook reentregue, status fora de ordem, janela fechando de madrugada e mídia que você não devia guardar. Seis defeitos com sintoma, causa e defesa.

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/vibecoding-primeiro-cliente-o-que-quebra.md)

Na sua máquina, tudo funciona. Você manda a mensagem, ela chega. O webhook dispara, a conversa aparece. Você testa por dez minutos, fecha o notebook e entrega para o primeiro cliente com a sensação, legítima, de que está pronto.

Na terça-feira ele liga dizendo que a mesma mensagem apareceu duas vezes. Na quinta, que o tique azul virou cinza. No domingo, que o sistema "parou de deixar responder" às quatro da manhã e voltou sozinho quando o cliente escreveu de novo. Nenhum desses três é bug no sentido comum: são comportamentos corretos de sistemas distribuídos encontrando um código que assumiu que o mundo é sequencial e acontece uma vez só. Aqui estão os seis mais frequentes, com sintoma, causa e a linha de defesa.

## 1\. A mesma mensagem aparece duas vezes

**Sintoma.** A conversa mostra "Bom dia" duplicado, com o mesmo horário. Sempre em produção, nunca no teste. E aparece mais quando o sistema está lento, o que confunde o diagnóstico.

**Causa.** Todo provedor de webhook reentrega. Se o seu endpoint demorar a responder, se a conexão cair no meio, ou às vezes sem motivo aparente, o mesmo evento chega de novo. O seu código lê o corpo e faz `insert`, porque nos testes cada evento chegou exatamente uma vez.

**Defesa.** Índice único no identificador externo da mensagem — o id que o provedor manda, não um id seu. A reentrega colide com o índice e é descartada **em silêncio**, sem log de erro: não é uma falha, é o funcionamento esperado. Tratar como erro enche o log de ruído e esconde os problemas de verdade.

O detalhe que quase todo mundo erra: a deduplicação precisa vir antes de qualquer efeito colateral. Se você grava a mensagem, dispara uma notificação e depois deduplica, o cliente recebe duas notificações de uma mensagem só.

## 2\. O tique azul vira cinza sozinho

**Sintoma.** O atendente vê a mensagem como lida, atualiza a tela e ela voltou para "entregue". Ou nunca sai de "enviada", mesmo com o cliente tendo respondido.

**Causa.** Os recibos de entrega não chegam na ordem em que aconteceram. `read` pode chegar antes de `delivered`, e o seu código faz `status = evento.status`, escrevendo por cima.

**Defesa.** Status não é um valor, é uma escada que só sobe: `enviada → entregue → lida`. Cada recibo compara antes de gravar, e recibo mais atrasado que o estado atual é ignorado. A exceção é `falha`, que é terminal e pode chegar de qualquer estado — quando a mensagem falha, ela falhou, independentemente do que chegou antes.

Duas armadilhas menores na mesma família. Recibo de entrega só se aplica a mensagem que **saiu** do seu sistema; mensagem recebida já nasce entregue, e tentar aplicar recibo nela cria estado impossível. E se você guarda "quando foi a primeira vez" para alguma métrica, grave com uma operação que só aceita valor menor, nunca sobrescrevendo — senão um recibo atrasado reescreve o passado.

## 3\. O sistema "não deixa responder" de madrugada

**Sintoma.** O atendente chega às oito da manhã, abre uma conversa de ontem e a caixa de digitação está bloqueada, ou o envio é recusado com um erro que fala de template. Uma hora depois o cliente escreve e tudo volta ao normal.

**Causa.** A janela de 24 horas. Depois que o cliente manda uma mensagem, você tem 24 horas para responder com texto livre. Passado o prazo, iniciar conversa exige um template aprovado pela Meta. A janela fecha pelo relógio, então ela fecha de madrugada, num horário em que ninguém está olhando.

**Defesa.** Três partes, e nenhuma é opcional.

Primeiro, a conversa guarda a data em que a janela expira, atualizada a cada mensagem **recebida**. Segundo, a tela lê esse campo e mostra a lista de templates no lugar da caixa de digitação quando a janela fechou — com uma frase dizendo por quê, senão o atendente conclui que o sistema quebrou. Terceiro, o envio valida no servidor de qualquer jeito: a tela é conveniência, e um `curl` ou uma aba antiga passariam por cima dela.

O mecanismo completo de template — como criar, o que a Meta recusa e por quê — está em [Templates do WhatsApp pela API](https://api-wa.me/blog/templates-whatsapp-api-criar-aprovar-enviar). Vale ler antes de desenhar a tela de conversa, não depois.

## 4\. As mensagens chegam na ordem errada

**Sintoma.** O bot manda um áudio e um menu de opções. No celular do cliente, o menu aparece primeiro e o áudio depois — a conversa fica sem sentido e parece que alguém programou errado.

**Causa.** Mídia enviada por URL só é entregue depois que a plataforma **baixa o arquivo**. Texto sai na hora. Se você dispara os dois em sequência imediata, o texto ultrapassa a mídia.

**Defesa.** Espaçar os envios automáticos, com um respiro maior depois de mídia do que depois de texto. Isso reduz a inversão a quase zero, mas é honesto dizer que **não a elimina**: garantia mesmo exigiria esperar o recibo de envio de cada mensagem antes de mandar a seguinte, prendendo o seu fluxo a um evento que pode demorar ou não chegar.

Na prática, o respiro resolve o caso real e o custo é conversas um pouco mais lentas — que por acaso também parecem mais naturais. Vale deixar o intervalo configurável, para conseguir desligá-lo em scripts de manutenção.

## 5\. O número perde qualidade, e depois perde o limite

**Sintoma.** Os envios começam a falhar depois de um certo volume diário, sem que nada no seu código tenha mudado. Ou a taxa de entrega cai e ninguém entende por quê.

**Causa.** A Meta atribui uma nota de qualidade ao número, derivada de bloqueios e denúncias de quem recebe, e essa nota governa quantas conversas você pode iniciar por dia. Disparo para lista comprada, mensagem sem contexto e template que parece propaganda derrubam a nota rápido.

**Defesa.** Três hábitos, e o primeiro é o que mais importa: **só mande para quem pediu**. Opt-in registrado, com data e origem, e opt-out que funcione de verdade — se alguém escreve "para", pare, e pare no mesmo minuto.

Os outros dois: acompanhe a nota em vez de descobri-la pela recusa, e não use o mesmo número para prospecção fria e para atendimento. O funcionamento do Tier e da nota está em [Quality Rating e limite de mensagens](https://api-wa.me/blog/quality-rating-limite-mensagens-whatsapp), com os números atuais.

Vale dimensionar o risco: número bloqueado não é uma inconveniência, é o canal de vendas do seu cliente desligado, e a conversa que vem em seguida é com você.

## 6\. Você está guardando mídia que não devia

**Sintoma.** Nenhum, por meses. Depois o disco enche, ou o cliente pede o contrato de tratamento de dados e alguém pergunta onde estão os arquivos que os clientes dele mandaram.

**Causa.** É a implementação óbvia. O webhook avisa que chegou uma imagem, você baixa, salva em disco ou num bucket, guarda o caminho no banco. Funciona de primeira, e cada foto de documento, comprovante e receita médica que passou pelo atendimento fica lá.

**Defesa.** Não guarde. Faça proxy: a tela pede o arquivo ao seu servidor, o servidor valida a sessão e busca o conteúdo na API de mensageria no momento do pedido. Zero disco, zero bucket, zero backup de arquivo — e, quando alguém perguntar o que você armazena, a resposta é "metadado e texto".

Isso tem um custo real, e vale dizer: cada visualização é uma ida à rede, e mídia muito antiga pode não estar mais disponível do lado de lá. Para atendimento, é uma troca que quase sempre compensa. Se o seu produto precisa de arquivo permanente — um contrato assinado, por exemplo —, aí é uma decisão consciente, com retenção definida e escrita no contrato. O que não pode é acontecer por acidente.

## O que esses seis têm em comum

Olhando junto, dá para ver o padrão, e o padrão é mais útil que a lista.

Nenhum deles aparece em teste feliz. Todos aparecem só com **tempo** e **volume** — duas coisas que não existem na sua máquina. E os seis vêm da mesma suposição implícita: a de que o mundo lá fora é como o seu ambiente de desenvolvimento, onde as coisas acontecem uma vez, na ordem, imediatamente e sem consequência jurídica.

A defesa geral, antes das específicas, é escrever três testes desconfortáveis assim que a integração funcionar: um que manda o mesmo webhook duas vezes, um que entrega os recibos de status na ordem inversa e um que tenta enviar com a janela vencida. São dez minutos de trabalho e eles encontram, de uma vez, metade desta lista.

O [dicionário de erros da API do WhatsApp](https://api-wa.me/blog/erros-api-whatsapp-como-tratar) ajuda na hora em que o código devolver um número que você não reconhece — que é como a maioria dessas coisas se apresenta na primeira vez.

## Conclusão

Nada aqui é sobre a qualidade do código que a IA escreveu para você. O código está certo para o mundo que foi descrito a ela, e o mundo que foi descrito a ela é o seu ambiente de desenvolvimento.

O que separa um protótipo de um sistema em uso não é elegância nem cobertura de teste. São seis suposições sobre o mundo: que o evento chega uma vez, na ordem, que o prazo não fecha sozinho, que a nota do número não cai, e que guardar arquivo é gratuito. Corrija as seis e o resto do seu sistema aguenta bem mais tráfego do que você imagina.

Se você ainda está montando o CRM, [as três partes que a IA não resolve](https://api-wa.me/blog/criar-crm-com-ia-o-que-a-ia-nao-resolve) cobre o que vem antes desta lista. Se o plano é vender, [o que falta no protótipo para virar produto](https://api-wa.me/blog/de-prototipo-a-produto-vender-o-crm-que-voce-criou) cobre o que vem depois.

### 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

Por que o webhook chega duas vezes se eu respondo 200?+

Porque o provedor reentrega quando não recebe a confirmação no prazo dele, e a sua resposta pode ter demorado, se perdido na rede ou chegado tarde por um segundo. Responder \`200\` antes de processar reduz muito a frequência, mas a única defesa confiável é a idempotência por identificador externo.

Como eu sei se a janela de 24 horas está aberta numa conversa?+

Guardando, na própria conversa, a data de expiração — atualizada toda vez que o cliente manda uma mensagem. Não dá para deduzir isso na hora do envio sem consultar o histórico, e não dá para confiar na memória do atendente: a janela fecha pelo relógio, muitas vezes de madrugada.

Preciso me preocupar com qualidade do número se mando pouca mensagem?+

Volume baixo ajuda, mas a nota vem de bloqueios e denúncias, não de quantidade. Cem mensagens não solicitadas fazem mais estrago que mil mensagens pedidas — e como o limite diário depende dessa nota, o problema aparece exatamente no dia em que o seu cliente mais precisa mandar.

Guardar mídia de conversa é problema de LGPD?+

É um risco que você assume, e frequentemente sem perceber que assumiu. No atendimento passam documentos, comprovantes e informação de saúde; guardá-los significa responder por eles no contrato, no backup e na exclusão a pedido. Fazer proxy sob autenticação evita a maior parte disso sem tirar nada do usuário.

Esses problemas somem se eu usar uma API gerenciada?+

Alguns somem, outros não. A conexão com a Meta, o token e o formato de webhook deixam de ser seus; a reentrega, a ordem dos recibos e a janela de 24 horas continuam sendo — elas são da natureza do canal, não do fornecedor. Qualquer um que prometa o contrário está descrevendo um sistema que você não vai reconhecer em produção.

## Continue lendo

[### 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)[### 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.](https://api-wa.me/blog/cursor-claude-code-integrar-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": "Vibecoding até o primeiro cliente: o que quebra fora da sua máquina",
  "description": "Webhook reentregue, status fora de ordem, janela fechando de madrugada e mídia que você não devia guardar. Seis defeitos com sintoma, causa e defesa.",
  "image": "https://api-wa.me/blog/vibecoding-primeiro-cliente-o-que-quebra/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/vibecoding-primeiro-cliente-o-que-quebra"
  },
  "keywords": "vibecoding, webhook whatsapp, idempotencia webhook, janela de 24 horas whatsapp, api whatsapp, primeiro cliente saas",
  "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": "Vibecoding até o primeiro cliente: o que quebra fora da sua máquina",
      "item": "https://api-wa.me/blog/vibecoding-primeiro-cliente-o-que-quebra"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Por que o webhook chega duas vezes se eu respondo 200?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Porque o provedor reentrega quando não recebe a confirmação no prazo dele, e a sua resposta pode ter demorado, se perdido na rede ou chegado tarde por um segundo. Responder `200` antes de processar reduz muito a frequência, mas a única defesa confiável é a idempotência por identificador externo."
      }
    },
    {
      "@type": "Question",
      "name": "Como eu sei se a janela de 24 horas está aberta numa conversa?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Guardando, na própria conversa, a data de expiração — atualizada toda vez que o cliente manda uma mensagem. Não dá para deduzir isso na hora do envio sem consultar o histórico, e não dá para confiar na memória do atendente: a janela fecha pelo relógio, muitas vezes de madrugada."
      }
    },
    {
      "@type": "Question",
      "name": "Preciso me preocupar com qualidade do número se mando pouca mensagem?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Volume baixo ajuda, mas a nota vem de bloqueios e denúncias, não de quantidade. Cem mensagens não solicitadas fazem mais estrago que mil mensagens pedidas — e como o limite diário depende dessa nota, o problema aparece exatamente no dia em que o seu cliente mais precisa mandar."
      }
    },
    {
      "@type": "Question",
      "name": "Guardar mídia de conversa é problema de LGPD?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "É um risco que você assume, e frequentemente sem perceber que assumiu. No atendimento passam documentos, comprovantes e informação de saúde; guardá-los significa responder por eles no contrato, no backup e na exclusão a pedido. Fazer proxy sob autenticação evita a maior parte disso sem tirar nada do usuário."
      }
    },
    {
      "@type": "Question",
      "name": "Esses problemas somem se eu usar uma API gerenciada?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Alguns somem, outros não. A conexão com a Meta, o token e o formato de webhook deixam de ser seus; a reentrega, a ordem dos recibos e a janela de 24 horas continuam sendo — elas são da natureza do canal, não do fornecedor. Qualquer um que prometa o contrário está descrevendo um sistema que você não vai reconhecer em produção."
      }
    }
  ]
}
```