Pular para o conteúdo
apiwpp

Como evitar mensagens duplicadas no WhatsApp com idempotência

Por que a API manda a mesma mensagem duas vezes e como o clientRef, o evento message.send_failed e webhooks idempotentes acabam com a duplicidade.

Equipe apiwpp · 13 min de leitura

O cliente reclama que recebeu a confirmação do pedido duas vezes. Às vezes três. Nos logs do seu sistema, tudo parece normal: uma requisição deu timeout, o cliente HTTP tentou de novo, e a segunda tentativa deu certo. Só que a primeira também tinha dado.

Mensagem duplicada no WhatsApp não é só um incômodo estético. Para quem recebe, parece spam; para o número que envia, cada duplicata é um motivo a mais para uma denúncia. E, quando a mensagem é uma cobrança ou um código de rastreio, a duplicata gera dúvida real: "paguei duas vezes?".

A boa notícia é que o problema tem nome e solução conhecidos: idempotência. Uma operação idempotente pode ser repetida quantas vezes for preciso e o efeito é o mesmo de uma vez só. Este guia mostra de onde vêm as duplicatas, como a chave clientRef da apiwpp torna o envio idempotente, o que fazer quando um envio aceito não vai acontecer e como fechar a outra ponta: os webhooks.

Por que a mesma mensagem sai duas vezes

Quase toda duplicata nasce do mesmo ponto cego: o seu sistema não sabe se a primeira tentativa funcionou. Três cenários respondem pela maioria dos casos.

Timeout na requisição

O seu código chama POST /connections/{id}/send e espera a resposta por 10 segundos. A rede engasga, o tempo esgota, e o seu código recebe um erro. Mas o erro diz só que a resposta não chegou. A requisição pode ter chegado, a mensagem pode ter entrado na fila, e o 202 pode estar perdido em algum lugar do caminho.

Um timeout é, literalmente, um "não sei". Tratar "não sei" como "falhou" e tentar de novo é o caminho mais curto para a duplicata.

Retentativa automática do cliente HTTP

Muitas bibliotecas de HTTP e SDKs repetem requisições sozinhas diante de erros de rede ou de respostas 5xx. É um bom comportamento para leituras. Para um envio, sem uma chave de idempotência, cada retentativa é um envio novo. O pior é que isso costuma estar escondido numa configuração padrão que ninguém lembra de ter ligado.

Job reprocessado

Filas de trabalho (Laravel Queues, BullMQ, Sidekiq, SQS) entregam cada job pelo menos uma vez. Um worker que cai depois de enviar e antes de marcar o job como concluído faz o job voltar para a fila. Um deploy no meio do processamento, um timeout de visibilidade curto demais ou um retry depois de uma exceção qualquer têm o mesmo efeito: o envio roda de novo.

Os três cenários têm uma coisa em comum. Não dá para eliminar a repetição (redes falham, workers caem), então a saída é fazer a repetição ser inofensiva. Se o conceito for novo, o glossário explica o que é idempotência em poucas linhas.

Um timeout não diz se o envio entrou na fila: com o mesmo clientRef, a repetição devolve o job original em vez de criar outro.

clientRef: a chave de idempotência do envio

Na apiwpp, a chave de idempotência do envio é o campo clientRef. Ele é o seu identificador daquele envio, com até 200 caracteres: o id do pedido, da notificação, da linha na sua fila. A regra é simples:

  • A primeira requisição com um clientRef numa conexão coloca a mensagem na fila e responde 202 com o job.
  • Uma repetição com o mesmo clientRef, na mesma conexão, responde 200 com o job original e "duplicate": true, e não coloca nada na fila.

A primeira requisição:

curl -s -X POST "https://api.apiwpp.com/connections/$ID/send" \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Olá, Ana! Seu pedido 1234 foi confirmado.", "clientRef": "pedido-1234-confirmacao"}'
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }

A mesma requisição, repetida depois de um timeout:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1, "duplicate": true }

Mesmo jobId, nenhuma mensagem a mais. Para o seu código, as duas respostas significam a mesma coisa: o envio está na fila. Os dois status (202 e 200) estão na faixa 2xx, então um if (response.ok) trata os dois casos do mesmo jeito.

A repetição é examinada antes de tudo

Um detalhe torna o clientRef especialmente útil: a API procura o clientRef logo depois de autenticar a chave e validar o corpo, antes de conferir o template e a conexão. Na prática, se o primeiro envio foi aceito, a repetição recebe o job original mesmo que, nesse meio-tempo, a conexão esteja reconectando.

O inverso também vale. Se a repetição responde um erro, como o 400 de conexão fora do ar, nenhuma requisição com aquele clientRef foi aceita: nada entrou na fila, e você pode tentar de novo mais tarde com o mesmo valor. Quando o enfileiramento falha, a reserva do clientRef é liberada.

A exceção é o 429 com Retry-After do limite de requisições por IP: aí a repetição nem chegou a ser examinada. Espere o tempo do cabeçalho e repita com o mesmo clientRef. O 429 com new_recipient_cap_reached (o teto de destinatários novos do número) também não coloca nada na fila; o guia sobre como evitar o bloqueio do número explica esse limite.

Como escolher um bom clientRef

A chave precisa identificar o aviso, não a tentativa. Três regras bastam:

  1. Derive de algo que já existe no seu domínio. pedido-1234-confirmacao, fatura-8812-vencimento, consulta-987-lembrete-vespera. Cada tipo de aviso para cada registro tem o próprio valor.
  2. Nunca gere um valor aleatório por tentativa. Um UUID novo a cada chamada transforma cada retentativa num envio novo, e a proteção some. Se precisar de um id gerado, gere uma vez, grave junto com o registro e reutilize.
  3. Lembre que a chave vale por conexão. O mesmo clientRef em dois números diferentes gera dois envios. Se o seu sistema pode escolher entre números, fixe o número do aviso antes do primeiro envio.
SituaçãoclientRefResultado
Primeira chamadapedido-1234-confirmacao202, mensagem na fila
Timeout e retentativapedido-1234-confirmacao200 com duplicate: true, nada novo na fila
Job reprocessado no dia seguintepedido-1234-confirmacao200 com duplicate: true
Aviso diferente do mesmo pedidopedido-1234-enviado202, mensagem nova
UUID aleatório por tentativasempre diferenteCada tentativa vira uma mensagem

Um envio com retentativa segura em Node.js

Com o clientRef fixo, a retentativa com espera crescente deixa de ser perigosa:

const API = 'https://api.apiwpp.com'
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

export async function sendOnce({ connectionId, to, message, clientRef }) {
  for (let attempt = 0; attempt < 4; attempt++) {
    let response
    try {
      response = await fetch(`${API}/connections/${connectionId}/send`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.APIWPP_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ to, message, clientRef }),
        signal: AbortSignal.timeout(10_000),
      })
    } catch {
      await sleep(1000 * 2 ** attempt) // timeout or network error: retry with the same clientRef
      continue
    }

    const body = await response.json()
    if (response.ok) return body // 202 queued, or 200 with duplicate: true
    if (response.status === 429) {
      const retryAfter = Number(response.headers.get('retry-after') ?? 60)
      throw Object.assign(new Error(body.error), { status: 429, retryAfter }) // reschedule the job
    }
    if (response.status >= 500) {
      await sleep(1000 * 2 ** attempt)
      continue
    }
    throw Object.assign(new Error(body.error), { status: response.status }) // other 4xx: fix the cause
  }
  throw new Error(`send ${clientRef} still unconfirmed after retries`)
}

O mesmo padrão, com o fluxo completo de envio, está no tutorial de Node.js em 5 minutos e na página de integração com Node.js. Em Laravel, o clientRef entra no Job e protege as retentativas da fila, como mostra o tutorial de WhatsApp com PHP e Laravel.

Por quanto tempo vale, e quando usar um clientRef novo

O clientRef fica reservado por 7 dias. Dentro desse prazo, qualquer repetição na mesma conexão devolve duplicate. Na prática, isso cobre com folga timeouts, retentativas de fila e reprocessamentos depois de um incidente.

A consequência que pega muita gente de surpresa: repetir o mesmo clientRef nunca reenvia a mensagem, nem quando você quer. Se o cliente pediu para receber o boleto de novo, ou se o envio original falhou depois de aceito, a mesma chave só vai devolver o job antigo com duplicate: true.

Para um reenvio deliberado, use uma chave nova, derivada da original: pedido-1234-confirmacao-2, fatura-8812-segunda-via. Assim o histórico continua legível e cada envio de verdade tem o próprio identificador.

Quero…Faço
Repetir porque não sei se a primeira chamada funcionouMesmo clientRef
Mandar de novo porque o cliente pediuclientRef novo, com sufixo
Mandar de novo depois de um message.send_failedclientRef novo, depois de conferir o motivo
Cancelar um envio que ainda está na filaDELETE /connections/{id}/queue/{jobId}

Guardar o jobId da resposta ao lado do registro também ajuda: com ele, você cancela um envio que ainda não saiu, por exemplo quando o pedido foi cancelado antes da confirmação chegar ao cliente.

message.send_failed: o envio aceito que não vai acontecer

Um 202 quer dizer "está na fila", não "foi entregue". A fila envia no ritmo que protege o número, e algo pode dar errado depois do aceite. Como a repetição com o mesmo clientRef só devolve duplicate, o seu sistema precisa de outro sinal para saber que aquele envio não vai sair. Esse sinal é o webhook message.send_failed.

Ele só existe para envios com clientRef: mais um motivo para mandar sempre um. O data do evento traz o clientRef, o jobId, o to como foi enviado, o número de tentativas em attempts e o motivo em reason. O messageId vem sempre null, porque a mensagem não chegou a existir no WhatsApp:

{
  "type": "message.send_failed",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-07-15T12:00:00.000Z",
  "data": {
    "clientRef": "pedido-1234-confirmacao",
    "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
    "messageId": null,
    "to": "5511988887777",
    "jid": "[email protected]",
    "phone": "+5511988887777",
    "reason": "not_on_whatsapp",
    "attempts": 1
  }
}

Cada reason pede uma reação diferente:

reasonO que houveO que fazer
not_on_whatsappO número não está no WhatsApp; não há novas tentativasMarque o contato e use outro canal. Reenviar não adianta
attempts_exhaustedTodas as tentativas de envio falharamInvestigue a conexão e reenvie com clientRef novo, se ainda fizer sentido
lease_expiredO envio travou na última tentativa, por exemplo num reinício; ele pode ter saído mesmo assimConfira antes de reenviar (veja abaixo)
reachout_timelockedA conta está num bloqueio temporário de novas conversas; o envio foi recusado sem ser tentadoPause os envios para contatos novos até o bloqueio acabar

O lease_expired merece atenção especial, porque é justamente o caso em que um reenvio apressado cria a duplicata que você queria evitar. Duas regras resolvem:

  • A prova de envio vale. Se, depois de um message.send_failed, chegar um message.outgoing ou um message.delivery com o mesmo clientRef, a mensagem saiu. Trate o envio como concluído.
  • Na dúvida, concilie. Sem nenhum evento depois do aceite, consulte o registro de mensagens com GET /messages?q=pedido-1234-confirmacao antes de decidir reenviar.

Para evitar o not_on_whatsapp, confira os números antes: POST /connections/{id}/contacts/check verifica até 100 de uma vez. E o reachout_timelocked é um aviso sério sobre a saúde do número, assunto do guia sobre como evitar o bloqueio do número.

O ciclo de vida de um envio com clientRef: aceito na fila, depois entregue (message.delivery) ou abandonado com o motivo (message.send_failed).

Do outro lado: webhooks sem processar duas vezes

Tornar o envio idempotente resolve metade do problema. A outra metade está nos eventos que voltam. A entrega de webhooks é pelo menos uma vez: se a resposta do seu servidor se perde, demora mais de 10 segundos ou não é 2xx, a apiwpp tenta de novo. Um reenvio feito por você no painel depois de um incidente também repete eventos.

Se o seu worker responde a cada message.incoming com uma mensagem automática, um evento repetido vira uma resposta duplicada. É a mesma duplicata, só que nascida do outro lado.

A solução é a mesma ideia do clientRef: derivar uma chave de cada evento e gravá-la numa tabela com restrição de unicidade. Se a chave já existe, o evento já foi processado:

CREATE TABLE whatsapp_events (
  event_key TEXT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- In the worker: zero rows inserted means the event was already handled
INSERT INTO whatsapp_events (event_key) VALUES ($1) ON CONFLICT DO NOTHING;

Para os eventos de envio, a chave sai do messageId e do jobId:

function eventKey(event) {
  const d = event.data ?? {}
  switch (event.type) {
    case 'message.delivery':
      return `dlv:${event.connectionId}:${d.messageId}:${d.status}` // one event per status
    case 'message.outgoing':
      return `out:${event.connectionId}:${d.messageId}`
    case 'message.send_failed':
      return `fail:${event.connectionId}:${d.jobId}` // messageId is always null here
    default:
      return null // see the webhook guide for the other types
  }
}

Três cuidados completam o quadro:

  • Status como progressão. O message.delivery chega uma vez por status (sent, delivered, read, failed). Uma mensagem já marcada como read no seu sistema não deve voltar para delivered se os eventos chegarem fora de ordem.
  • O clientRef liga o evento ao registro. Ele volta em message.outgoing, message.delivery e message.send_failed. A associação entre clientRef e messageId vale por 72 horas; depois disso, um status tardio pode chegar com clientRef: null, e você correlaciona pelo messageId que guardou.
  • Responda rápido, processe depois. A rota do webhook verifica a assinatura, grava o evento e responde 204. A checagem da chave e a regra de negócio ficam num worker.

O tutorial de webhooks do WhatsApp traz a verificação da assinatura HMAC, a chave para os demais tipos de evento e o reenvio de entregas pelo painel. A página de webhooks assinados lista todos os eventos.

Um checklist anti-duplicata

Para revisar a sua integração em poucos minutos:

PontoPerguntaResposta certa
EnvioTodo /send leva um clientRef?Sim, derivado do registro e do tipo de aviso
EnvioA chave muda entre tentativas?Nunca; só muda num reenvio deliberado
EnvioO código trata 200 com duplicate: true como sucesso?Sim, é o mesmo job
EnvioO jobId fica guardado?Sim, para cancelar ou conciliar
FalhaO worker trata message.send_failed por reason?Sim, com cuidado extra no lease_expired
WebhookCada evento tem uma chave única gravada?Sim, com restrição de unicidade no banco
WebhookRespostas automáticas dependem da chave do evento?Sim, para não responder duas vezes

Um exemplo concreto de onde tudo isso importa é a confirmação de pedido de uma loja: clientRef igual ao id do pedido mais o tipo de aviso, nunca a mesma confirmação duas vezes, e o status de entrega de volta pelo webhook. O guia de notificações de pedido para e-commerce desenvolve esse caso, e a página de idempotência com clientRef resume o recurso.

Como começar hoje

  1. Liste os avisos que o seu sistema envia (confirmação, pagamento, envio, lembrete) e defina o formato do clientRef de cada um, como pedido-<id>-confirmacao.
  2. Grave o clientRef junto com o registro antes do primeiro envio e passe o mesmo valor em todas as tentativas.
  3. Trate 202 e 200 com duplicate: true como sucesso, e guarde o jobId da resposta.
  4. Crie um handler para message.send_failed que decida por reason e, no lease_expired, concilie com GET /messages?q= antes de reenviar.
  5. Grave uma chave única por evento de webhook e só execute a regra de negócio quando a chave for nova.
  6. Crie sua conta na apiwpp, conecte um número e repita um envio com o mesmo clientRef para ver o duplicate: true na prática. Os planos por número estão em preços.

Perguntas frequentes

Por que a API do WhatsApp enviou a mesma mensagem duas vezes?

Quase sempre porque o seu sistema repetiu a requisição sem saber que a primeira tinha funcionado: um timeout, uma retentativa automática do cliente HTTP ou um job reprocessado pela fila. Sem uma chave de idempotência, cada repetição vira um envio novo. Com o mesmo clientRef, a repetição devolve o job original e não coloca nada na fila.

O que acontece se eu repetir um envio com o mesmo clientRef?

Se a primeira requisição foi aceita, a repetição responde 200 com o job original e "duplicate": true, sem enfileirar outra mensagem. Isso vale por 7 dias e na mesma conexão. Se a primeira requisição respondeu um erro, nada foi aceito e a repetição com o mesmo valor enfileira normalmente.

Como reenvio de propósito uma mensagem que já mandei?

Use um clientRef novo, derivado do original, como pedido-1234-confirmacao-2. Repetir a chave antiga só devolve duplicate, mesmo que o envio original tenha falhado. Se o motivo foi lease_expired, confira antes pelo registro de mensagens se a mensagem não saiu mesmo assim.

O que significa o evento message.send_failed?

É o aviso de que um envio aceito com clientRef não vai acontecer. O campo reason diz o motivo: not_on_whatsapp, attempts_exhausted, lease_expired ou reachout_timelocked. Envios sem clientRef não geram esse evento, por isso vale mandar a chave em todo envio.

Posso usar um UUID aleatório como clientRef?

Pode, desde que ele seja gerado uma vez, gravado junto com o registro e reutilizado em todas as tentativas. O erro comum é gerar um UUID novo a cada chamada: aí cada retentativa tem uma chave diferente e vira uma mensagem nova. Um valor derivado do seu domínio, como o id do pedido, é mais simples de auditar.

Como evito processar o mesmo webhook duas vezes?

Derive uma chave de cada evento (por exemplo, messageId e status no message.delivery, ou jobId no message.send_failed) e grave-a numa tabela com restrição de unicidade antes de processar. Se a chave já existir, descarte o evento e responda 2xx mesmo assim. A entrega é pelo menos uma vez, então a repetição é esperada.


Leia também:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.