Pular para o conteúdo
apiwpp
Recurso

Idempotência com clientRef: sem mensagens duplicadas

Com o clientRef, repetir um envio depois de um timeout devolve o job original em vez de duplicar a mensagem, e cada webhook volta ligado ao seu registro.

Atualizado em

Uma requisição HTTP que estourou o tempo não diz se o servidor chegou a processar o pedido. Se você repete, corre o risco de mandar a mesma cobrança duas vezes para o cliente. Se não repete, pode ser que a mensagem nunca tenha saído. Filas de jobs, retentativas automáticas do cliente HTTP e reprocessamentos depois de um deploy criam o mesmo dilema todos os dias.

A idempotência resolve isso: repetir a mesma operação não tem efeito duplicado. Na apiwpp, a chave de idempotência é o campo clientRef do envio.

O clientRef como chave de idempotência

O clientRef é o seu identificador daquele envio: o id do pedido, da notificação, da linha na sua fila. Ele aceita até 200 caracteres e é opcional, mas recomendado em todo envio que o seu sistema possa repetir:

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

O clientRef fica reservado por 7 dias. Se o enfileiramento falhar, ou seja, se a resposta foi um erro, a reserva é liberada e a repetição enfileira normalmente.

A apiwpp procura o clientRef logo depois de autenticar a chave e validar o corpo, antes de conferir a conexão. Assim, a repetição de um envio já aceito recebe o job original mesmo que, nesse meio-tempo, o número esteja reconectando. Um 429 com Retry-After vindo do limite de requisições da API é diferente: a repetição nem chegou a ser examinada, então espere e repita.

Na prática, o seu código fica simples: em caso de timeout, erro de rede ou 5xx, repita a mesma requisição com o mesmo clientRef até receber 202 ou 200.

O clientRef volta nos webhooks

A segunda função do clientRef é ligar cada evento ao registro que o originou. Ele volta nos webhooks daquela mensagem:

EventoQuando chega
message.outgoingA mensagem saiu, com origin: API (só em projetos com esse evento ativado)
message.deliveryCada mudança de status: sent, delivered, read ou failed, junto com o messageId do WhatsApp
message.send_failedA apiwpp desistiu do envio; messageId é null e reason diz o motivo

Com isso, você atualiza o pedido 1234 para "entregue" ou "lido" direto pelo clientRef, sem precisar guardar o jobId. A associação entre clientRef e messageId vale por 72 horas: um status que chegue depois disso pode vir com clientRef: null, e a correlação passa a ser pelo messageId.

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

Um 202 quer dizer que a mensagem entrou na fila, não que ela saiu. Quando um envio com clientRef não vai acontecer, a apiwpp avisa com message.send_failed e o motivo em reason:

reasonO que houve
attempts_exhaustedTodas as tentativas de envio falharam
lease_expiredO envio travou na última tentativa, por exemplo num reinício; ele pode ter saído mesmo assim
not_on_whatsappO número não está no WhatsApp; não há novas tentativas
reachout_timelockedA conta está num bloqueio temporário de novas conversas; o envio foi recusado sem ser tentado

Só envios com clientRef geram esse evento, o que é mais um motivo para mandá-lo sempre. Se depois de um message.send_failed chegar um message.outgoing ou um message.delivery do mesmo clientRef, a prova de envio vale: a mensagem saiu. Sem nenhum evento, concilie pelo registro de mensagens com GET /messages?q=<clientRef>.

Reenvio deliberado com um clientRef novo

Repetir com o mesmo clientRef depois de um message.send_failed só devolve duplicate: true, porque aquele envio já foi aceito uma vez. Para mandar a mensagem de novo de propósito, use outro valor, por exemplo pedido-1234-confirmacao-2.

Uma boa convenção é montar o clientRef a partir do que torna o envio único no seu sistema:

O passo a passo completo, com os motivos mais comuns de duplicidade e o outro lado da história (consumir webhooks sem processar o mesmo evento duas vezes), está no guia como evitar mensagens duplicadas no WhatsApp com idempotência.

Perguntas frequentes

O clientRef é obrigatório?

Não, mas é recomendado. Sem ele, a apiwpp não tem como saber que duas requisições são o mesmo envio, e uma repetição depois de um timeout coloca outra mensagem na fila. Ele também é o que faz o evento message.send_failed ser emitido.

Por quanto tempo o mesmo clientRef é considerado repetido?

Por 7 dias a partir do envio aceito. Dentro desse prazo, qualquer requisição com o mesmo clientRef na mesma conexão responde 200 com o job original e duplicate: true.

Posso usar o mesmo clientRef em números diferentes?

Pode. A verificação é por conexão: o mesmo valor em outra conexão é um envio diferente. Ainda assim, um identificador único no seu sistema inteiro facilita a leitura dos logs.

Como mando de novo uma mensagem que falhou?

Com um clientRef novo. O mesmo valor só devolve o job original, mesmo que ele tenha terminado em message.send_failed.

Todos: Recursos →

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Cada número conectado tem uma fila que envia no ritmo de uma pessoa: limites por minuto, hora e dia, intervalo aleatório entre envios e um teto de destinatários novos por dia. Mensagens ilimitadas dentro desses limites.

Conecte seu primeiro número hoje.

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