BLOG
Enviar mensagem WhatsApp API sem duplicar: guia prático
Enviar mensagem WhatsApp API sem duplicar: entenda por que timeouts e retries repetem envios e veja como usar chave de idempotência e fila.

Para enviar mensagem WhatsApp API sem duplicar, não repita a chamada às cegas quando houver timeout. Grave o envio no seu banco antes, use uma chave ligada ao evento de negócio e consulte o estado da mensagem antes de qualquer nova tentativa. Neste guia você vê por que a duplicidade acontece, como evitá-la no código e onde o FlowZap ajuda.
Principais pontos
- O timeout não prova que a mensagem falhou: ela pode ter sido aceita e só a resposta se perdeu.
- A chave de idempotência deve vir do negócio (ex.: cobrança 1049), não de um UUID novo a cada tentativa.
- Grave o estado do envio antes da chamada HTTP e reconcilie antes de reenviar, com espera crescente.
- Webhooks também repetem: responda rápido, processe depois e ignore eventos já vistos.
- Fila com intervalo entre envios evita rajadas, e os estados na fila, enviada, entregue e lida mostram onde cada mensagem está.
- Repetir mensagem para a mesma pessoa tem custo de relação e de LGPD; só envie a quem autorizou.
Por que a mensagem duplica ao enviar mensagem WhatsApp API
Enviar mensagem WhatsApp API parece simples: um POST, uma resposta 200, pronto. O problema aparece quando a resposta não chega.
Imagine uma cobrança de R$ 120 disparada para um cliente. A API aceita o pedido e despacha a mensagem, mas a conexão cai antes de o HTTP 200 voltar ao seu servidor. Seu código lê isso como falha, tenta de novo e o cliente recebe a mesma cobrança duas vezes. Quem atende a reclamação depois sabe como isso soa: parece descuido, mas na verdade é um bug de arquitetura.
A referência de envio da Meta mostra o que o pedido retorna quando dá certo. O que fazer quando ele não retorna é responsabilidade sua. Relatos de quem integrou a Cloud API, como este da equipe RelayOS, tratam falha de rede e de resposta como parte normal do trabalho.
O timeout que esconde uma resposta de sucesso
Timeout de leitura significa apenas que sua aplicação desistiu de esperar. Não significa que a mensagem não saiu. A API pode ter processado tudo e só a confirmação se perdeu no caminho. Por isso, deu timeout não é o mesmo que falhou.
Retry cego na aplicação
É o clássico bloco que captura qualquer exceção e chama a função de envio de novo. Sem checar o que aconteceu antes, cada tentativa pode virar uma mensagem nova.
O mesmo vale para filas de tarefas configuradas para reexecutar jobs que não terminaram dentro do prazo. O job estourou o tempo, mas a mensagem já tinha saído.
Duas instâncias disparando o mesmo job
Se você tem mais de um worker lendo a tabela de envios pendentes, dois deles podem pegar o mesmo registro quase ao mesmo tempo. Cada um faz sua chamada e o cliente recebe duas mensagens, sem que nenhum worker tenha errado sozinho.
Essa concorrência é um dos motivos para travar o registro antes da chamada, como você verá adiante.
API do WhatsApp: como funciona e onde a duplicidade escapa
Se você chegou aqui pesquisando como a API do WhatsApp funciona, o resumo é este: você faz um pedido REST com destinatário e conteúdo, a mensagem entra no fluxo de envio e a confirmação de cada etapa chega depois, por estados e webhooks. O pedido e a confirmação são momentos diferentes.
Do pedido de envio à confirmação
O caminho típico tem três passos:
- Pedido: seu sistema chama a API com o telefone e o conteúdo.
- Aceite: a plataforma responde que recebeu o pedido.
- Acompanhamento: novos eventos informam se a mensagem foi enviada, entregue e lida.
O ponto frágil é o intervalo entre o pedido e o aceite chegar até você. É nesse espaço que o timeout aparece e que o reenvio às cegas acontece.
O que a API garante e o que fica com você
Não parta do princípio de que a API deduplica sozinha. Cada provedor tem as suas regras: alguns aceitam uma chave de idempotência, outros não oferecem nada parecido. Confira sempre a documentação de envio da Meta e a do provedor que você usa. Se a regra não estiver clara, assuma que a proteção é sua.
Se a dúvida for sobre custo, veja API do WhatsApp é paga? O que muda em outubro de 2026. Para a API do FlowZap, o caminho é a documentação.
Idempotência na prática: chave, estado e reconciliação
Idempotência é a propriedade de repetir um pedido sem repetir o efeito. Para quem busca idempotência em API de WhatsApp, a ideia se resume a três hábitos: chave estável, estado gravado antes e consulta antes de reenviar. Esse é o raciocínio de materiais sobre envios idempotentes e monitoramento e sobre idempotência em APIs de WhatsApp.
Chave ligada ao evento de negócio, não UUID aleatório
A chave deve responder à pergunta: que fato do negócio gerou esta mensagem? Exemplos:
cobranca-1049-lembrete- hash de
id do destinatário + id do evento
Um UUID novo a cada tentativa é o erro mais comum. Cada retry parece um pedido inédito, então nada impede a repetição. A chave só funciona se for a mesma em todas as tentativas daquele envio.
Algumas implementações e proxies de envio tratam pedidos repetidos com o mesmo conteúdo, dentro de uma janela de tempo, devolvendo o mesmo identificador sem despachar outra mensagem. Isso é característica dessas implementações, não uma regra que você possa presumir em qualquer API. Verifique no seu caso.
Trave o estado antes da chamada HTTP
Antes de falar com a API, grave no seu banco um registro com a chave e o estado processando. Se outro worker tentar o mesmo envio, a chave única ou um lock transacional o barra. Pode ser SKIP LOCKED no PostgreSQL ou um lock em Redis.
Um esqueleto de pseudo-código:
envio = gravar(chave, estado='processando') # falha se a chave já existe
se envio já existia: parar
resposta = chamar_api(destino, conteudo)
se resposta ok: gravar(estado='aceita', id_da_mensagem)
se timeout: gravar(estado='incerto') e agendar reconciliação
Depois do timeout: consulte, espere, só então tente de novo
O estado incerto é honesto: você não sabe se a mensagem saiu. A reconciliação olha o que já se sabe antes de agir:
- Existe um identificador de mensagem gravado?
- Chegou algum webhook de envio ou entrega para essa chave?
- Algum estado da mensagem já passou de na fila?
Só se nada indicar que a mensagem saiu você libera nova tentativa. Use espera crescente (1 min, 2 min, 4 min, por exemplo) e um limite de tentativas.
| Situação | Ação recomendada |
|---|---|
| Sucesso (resposta 2xx com identificador) | Gravar o identificador e marcar como aceita. Não repetir. |
| Erro 4xx (pedido inválido, número com problema) | Não repetir igual. Corrigir o dado ou registrar a falha. |
| Erro 5xx (falha do lado da API) | Reconciliar e tentar de novo com espera crescente e limite. |
| Timeout (sem resposta) | Marcar como incerto, consultar estado e webhooks, só então reenviar. |
Se aparecer erro de limite de taxa (como o 429), reduza o ritmo em vez de insistir. Mais adiante você vê como a fila ajuda nisso.
Retry de webhook: como não processar o mesmo evento duas vezes
A duplicidade não acontece só na saída. No recebimento, quem envia o evento espera uma resposta rápida. Se o seu endpoint demora porque faz muita coisa antes de responder, a conexão estoura o tempo, o remetente tenta de novo e sua lógica roda duas vezes.
Discussões como esta no Stack Overflow e esta na comunidade da Meta mostram desenvolvedores lidando com notificações que chegam mais de uma vez. Quem pesquisa retry de webhook do WhatsApp costuma estar nessa situação.
Responda rápido, processe depois
A receita é simples:
- Valide a assinatura, se houver.
- Devolva 200 imediatamente.
- Coloque o evento numa fila interna.
- Processe com calma em outro worker.
Assim, o tempo de resposta deixa de depender da sua regra de negócio, seja atualizar um CRM, mandar um e-mail ou gerar uma nota.
Guarde o ID do evento e ignore repetidos
Trate todo evento como possivelmente repetido. Ao receber, tente registrar o ID do evento numa tabela com chave única ou numa chave Redis com validade. Se já existir, descarte. Este passo a passo com Redis mostra a ideia aplicada.
Se você monta o recebimento no n8n, veja Webhook WhatsApp no n8n: passo a passo. Os webhooks do FlowZap são assinados e têm novas tentativas. Por isso, o seu lado precisa estar preparado para receber o mesmo evento mais de uma vez. Os detalhes estão em /docs.
Fila de mensagens WhatsApp: estados na fila, enviada, entregue e lida
Aqui o foco é usar o estado como decisão de código, não explicar cada ícone. Cada mensagem passa por uma sequência: na fila, enviada, entregue e, se a pessoa abrir, lida. Quem acompanha essa sequência sabe onde a mensagem está e não precisa adivinhar.
Estados como trava contra reenvio
| Estado | O que significa | O que fazer no código |
|---|---|---|
| Na fila | Pedido registrado, ainda não saiu | Não crie outro pedido para o mesmo evento. |
| Enviada | Aceita para envio | Não reenvie. |
| Entregue | Chegou ao aparelho da pessoa | Encerrar o envio como concluído. |
| Lida | A pessoa abriu a conversa | Opcional: use para follow-up, nunca para reenviar. |
A regra prática: se o estado já passou de na fila, um novo envio do mesmo evento é duplicidade. O webhook de status é a sua fonte para saber disso sem depender da resposta HTTP que pode ter se perdido.
Quando reenviar e quando esperar
Se a mensagem ficou na fila por muito tempo, o problema está na fila, não no destinatário. Investigue antes de criar outro pedido.
Se ficou enviada e não virou entregue, o aparelho pode estar desligado ou sem internet, e isso costuma se resolver sozinho. Reenviar só faz sentido quando a falha está registrada e a causa foi corrigida.
No FlowZap, você acompanha esses quatro estados em cada mensagem, no console. Para receber os eventos no seu sistema, veja a documentação.
Envio sem duplicidade e fila com intervalo no FlowZap
Construir tudo isso do zero dá trabalho. Quando faz sentido, o FlowZap resolve parte do problema na plataforma, e o que está descrito abaixo é o que o produto oferece hoje.
Texto com envio sem duplicidade
O envio de mensagens de texto no FlowZap tem proteção contra duplicidade. Na prática, se o seu sistema repetir o mesmo pedido por causa de um timeout, a mensagem não sai de novo para o cliente.
A documentação explica como identificar o pedido na chamada. Use sempre o mesmo identificador em todas as tentativas do mesmo envio e confira lá os detalhes antes de implementar.
Isso não dispensa o seu controle. Continue gravando o estado antes e reconciliando depois. A proteção da plataforma é uma segunda camada, não um motivo para tirar a primeira.
Fila com intervalo entre envios
Mandar dezenas de mensagens ao mesmo tempo causa dois problemas. O primeiro é a rajada, que pode estourar limites de taxa. O segundo é a concorrência na gravação, que favorece repetição quando várias instâncias agem juntas.
No FlowZap, as mensagens entram numa fila com intervalo entre envios e saem em ritmo controlado. Você acompanha cada uma pelos estados na fila, enviada, entregue e lida. Para avisos em lote ao seu público autorizado, isso dá previsibilidade e facilita a reconciliação.
Quando usar modelos com variáveis
Para avisos, cobranças e lembretes, os modelos de mensagem com variáveis (nome, valor, data) evitam montar o texto no código. Eles são enviados para uma pessoa por vez, na hora ou agendados, pelo console ou pela API.
Isso encaixa bem com a chave de negócio: um lembrete por cobrança, um envio por chave. Se quiser ver tudo o que a plataforma faz, vá a /produto. Para ideias de uso com cobrança e atendimento, veja os casos de uso.
Duplicidade, LGPD e boa relação com o cliente
Mensagem repetida incomoda o cliente e tem um lado legal. Dá para tratar isso com calma, sem alarmismo.
Telefone e conversas são dados pessoais
Pela LGPD (Lei nº 13.709/2018, art. 5º, I), número de telefone e registros de conversa são dados pessoais. Falhas técnicas que repetem contato pesam contra os princípios de segurança e de prevenção (art. 6º, VII e VIII): quem trata dados deve adotar medidas para evitar danos.
A ANPD publica materiais orientativos, como as notas técnicas 19 e 58/2025. Vale ler com o seu jurídico, que sabe como elas se aplicam ao seu caso.
Só envie a quem autorizou
Deduplicar não é licença para disparar. Mensagens só devem ir para quem autorizou receber, com o consentimento registrado. Não compre listas, não use números descartáveis e não tente contornar bloqueios. Uma mensagem a mais para quem não pediu contato é pior que duas para quem pediu.
Checklist final
- A chave de idempotência vem do evento de negócio, não de um UUID novo.
- O estado do envio é gravado antes da chamada HTTP.
- Timeout vira incerto, não falhou.
- Antes de reenviar, você consulta identificador, estado e webhooks.
- O webhook responde rápido e ignora IDs de evento já vistos.
- O destinatário autorizou receber a mensagem.
Para os detalhes de API e webhooks do FlowZap, consulte /docs. Se tiver dúvidas sobre o seu caso, fale pelo /contato.
Comece com o FlowZap
Veja o que o FlowZap faz e compare os planos. Para criar a conta, basta o nome da empresa, um e-mail e uma senha: o cadastro não pede cartão de crédito, e o pagamento é por Pix ou cartão de crédito, sem fidelidade.
Perguntas frequentes
Por que a mensagem duplica ao enviar pela API do WhatsApp?
Geralmente por timeout ou erro de rede que esconde a resposta de sucesso. A mensagem já saiu, mas o código assume falha e reenvia. Também ocorre quando dois workers pegam o mesmo registro pendente ao mesmo tempo.
Como evitar envio duplicado no WhatsApp?
Grave o envio no banco antes de chamar a API, use uma chave ligada ao evento de negócio (como cobranca-1049-lembrete) e, após um timeout, consulte o estado da mensagem antes de tentar de novo, com espera crescente entre as tentativas.
O que é idempotência numa API de WhatsApp?
É repetir o mesmo pedido sem repetir o efeito. Na prática, você manda a mesma chave em todas as tentativas de um envio, e quem recebe reconhece o repetido. Nem todo provedor oferece isso, então confira a documentação e proteja também no seu lado.
O webhook do WhatsApp pode chegar repetido?
Sim, trate todo evento como possivelmente repetido. Responda 200 logo, coloque o evento numa fila interna e guarde o ID do evento numa tabela com chave única ou no Redis. Se o ID já existir, descarte o evento.
Qual a vantagem de uma fila de mensagens no WhatsApp?
A fila com intervalo entre envios evita rajadas e reduz concorrência de gravação. As mensagens saem em ritmo controlado e você acompanha cada uma como na fila, enviada, entregue ou lida, o que ajuda a não reenviar por engano.
Fontes
Atenda o WhatsApp da empresa em equipe.
Conecte o número por QR code e responda pelo navegador, com a API para integrar seus sistemas.
Cadastro sem cartão de crédito · Pix ou cartão de crédito, sem fidelidade


