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" }'
- A primeira requisição com um
clientRefnuma conexão coloca a mensagem na fila e responde202com o job:jobId,scheduledAteposition. - Uma repetição com o mesmo
clientRef, na mesma conexão, responde200com o job original e"duplicate": true. Nada novo entra na fila:
{ "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:
| Evento | Quando chega |
|---|---|
message.outgoing | A mensagem saiu, com origin: API (só em projetos com esse evento ativado) |
message.delivery | Cada mudança de status: sent, delivered, read ou failed, junto com o messageId do WhatsApp |
message.send_failed | A 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:
reason | O que houve |
|---|---|
attempts_exhausted | Todas as tentativas de envio falharam |
lease_expired | O envio travou na última tentativa, por exemplo num reinício; ele pode ter saído mesmo assim |
not_on_whatsapp | O número não está no WhatsApp; não há novas tentativas |
reachout_timelocked | A 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:
pedido-1234-confirmacaoepedido-1234-enviosão mensagens diferentes do mesmo pedido;lembrete-consulta-5678-vesperanão se repete mesmo se o job do lembrete rodar duas vezes;- um sufixo de tentativa (
-2,-3) marca um reenvio decidido por uma pessoa ou por uma regra do 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.
Outros recursos
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.