Idempotência
Repita um envio com segurança depois de um timeout usando o clientRef e ligue cada webhook da mensagem ao registro certo do seu sistema.
O clientRef é o seu identificador de um envio: o id do pedido, da notificação, da linha na sua fila de saída. É um campo opcional do corpo de POST /connections/{id}/send, com até 200 caracteres, e faz duas coisas:
- torna o envio idempotente: repetir a requisição não duplica a mensagem;
- volta nos webhooks daquela mensagem, para você saber a qual registro cada evento pertence.
Repetir sem duplicar
Um timeout não diz se a mensagem entrou na fila. Com clientRef, repita a mesma requisição sem medo:
- A primeira requisição com um
clientRefnuma conexão enfileira a mensagem e responde202com o job. - Uma repetição com o mesmo
clientRef, na mesma conexão, responde200com o job original e"duplicate": true, e não enfileira nada.
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "message": "Seu pedido 1234 saiu para entrega.", "clientRef": "pedido-1234"}'{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }A mesma requisição, repetida:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1, "duplicate": true }Trate 200 com duplicate: true como sucesso: a mensagem já está na fila (ou já saiu). Se a repetição chegar enquanto a primeira requisição ainda está sendo enfileirada, scheduledAt e position vêm null; o jobId já é o definitivo.
O que a reserva cobre
- Por conexão. O
clientRefé reservado na conexão do envio. O mesmo valor em outra conexão é outro envio. - Por 7 dias. Depois de aceito, o
clientReffica reservado por 7 dias, o mesmo tempo que o job fica guardado. - Só envios aceitos. Uma requisição que termina em erro não reserva nada: se o enfileiramento falhar, a reserva é liberada na hora, e a repetição enfileira normalmente. Se o gateway cair entre a reserva e o enfileiramento, a reserva provisória expira sozinha em 60 segundos.
Por que uma repetição nunca vira erro
A apiwpp procura o clientRef antes de conferir o template, o status da conexão, a cota do plano e o limite de destinatários novos. Então a repetição de um envio aceito recebe o job original mesmo que, nesse meio-tempo, a conexão esteja reconectando ou a cota tenha acabado. Na prática, numa repetição:
| Resposta | O que quer dizer |
|---|---|
200 com duplicate: true | Um envio anterior com esse clientRef foi aceito. Nada novo foi enfileirado |
202 | Nenhum envio anterior foi aceito; este foi, agora |
400, 404 ou 429 de cota (com X-Usage-Percent) ou new_recipient_cap_reached | Nenhuma requisição com esse clientRef foi aceita: nada foi enfileirado |
429 com Retry-After, sem X-Usage-Percent nem error de destinatários novos | Limite de requisições: a repetição nem chegou a ser examinada. Espere e repita |
401, 403 ou 402 | A chave, o escopo ou a assinatura da organização barraram a requisição antes da busca pelo clientRef. Não diz nada sobre o envio anterior |
503 com Retry-After | A conexão está mudando de instância. Espere e repita |
O guia Erros detalha cada status, e Limites de envio explica os três tipos de 429.
Um cliente que repete com segurança
Gere o clientRef uma vez, a partir do seu registro, e reutilize-o em todas as tentativas daquele envio. Repita em falhas de rede, 429 e 5xx, com espera crescente; não repita um 400, 401, 402, 403 ou 404 sem corrigir a causa.
const BASE = 'https://api.apiwpp.com'
async function sendOnce(connectionId, body, { attempts = 5 } = {}) {
for (let attempt = 1; ; attempt++) {
let res
try {
res = await fetch(`${BASE}/connections/${connectionId}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(body), // o mesmo clientRef em todas as tentativas
signal: AbortSignal.timeout(15_000),
})
} catch (err) {
// Timeout ou erro de rede: a mensagem pode ter entrado na fila. Repetir é seguro.
if (attempt >= attempts) throw err
await sleep(backoff(attempt))
continue
}
if (res.status === 202 || res.status === 200) return res.json() // 200 = duplicate: true
const retryable = res.status === 429 || res.status >= 500
if (!retryable || attempt >= attempts) {
throw new Error(`send failed: ${res.status} ${await res.text()}`)
}
const retryAfter = Number(res.headers.get('retry-after'))
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt))
}
}
const backoff = (attempt) => Math.min(1000 * 2 ** attempt, 30_000)
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
await sendOnce(process.env.CONNECTION_ID, {
to: '5511988887777',
message: 'Seu pedido 1234 saiu para entrega.',
clientRef: 'pedido-1234',
})# --retry repete a mesma requisição (o mesmo corpo, o mesmo clientRef) em timeouts,
# 408, 429, 500, 502, 503 e 504, respeitando o Retry-After.
curl -s --retry 5 --max-time 15 \
-X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "message": "Seu pedido 1234 saiu para entrega.", "clientRef": "pedido-1234"}'Correlacionar os eventos
O clientRef volta nos webhooks da mensagem, e você liga cada evento ao seu registro sem precisar saber antes o messageId do WhatsApp:
| Evento | Quando |
|---|---|
message.outgoing | A mensagem saiu, com origin: API (só para projetos com emitOutgoing: true) |
message.delivery | Cada mudança de status (sent, delivered, read, failed), junto com o messageId do WhatsApp |
message.send_failed | A apiwpp desistiu do envio; messageId é null e reason diz por quê |
{
"type": "message.delivery",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-24T12:00:02.000Z",
"data": {
"messageId": "3EB0C767D26A1D8A3F52",
"status": "delivered",
"recipient": "5511988887777",
"jid": "[email protected]",
"phone": "+5511988887777",
"clientRef": "pedido-1234"
}
}A apiwpp gera o messageId e o associa ao clientRef antes de entregar a mensagem ao WhatsApp, então o eco de um envio pela API nunca chega como origin: PHONE. A associação vale por 72 horas: depois disso, um status tardio (um celular que ficou desligado no fim de semana, por exemplo) chega com clientRef: null. Por isso, guarde o messageId do primeiro evento que o trouxer e, daí em diante, correlacione pelos dois.
Um message.delivery com status: failed pode trazer reason: reachout_timelocked: o WhatsApp recusou a mensagem como contato frio. Ela não é tentada de novo; veja Bloqueio temporário de novas conversas.
message.send_failed: o envio aceito que não vai acontecer
Depois do 202, a apiwpp tenta o envio até 3 vezes, com espera crescente entre as tentativas. Quando ela desiste, um envio com clientRef gera o evento message.send_failed; um envio sem clientRef não gera nenhum evento, porque não haveria como correlacioná-lo. É o único aviso de que um envio aceito não vai sair: a repetição com o mesmo clientRef continua respondendo duplicate.
{
"type": "message.send_failed",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-24T12:00:05.000Z",
"data": {
"clientRef": "pedido-1234",
"jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
"messageId": null,
"to": "5511988887777",
"jid": "[email protected]",
"phone": "+5511988887777",
"reason": "not_on_whatsapp",
"attempts": 1
}
}messageId é sempre null, to é o destinatário como você o enviou e attempts diz quantas tentativas foram feitas. reason diz o motivo:
reason | O que houve | O que fazer |
|---|---|---|
attempts_exhausted | Todas as tentativas de envio falharam | Confira a conexão e reenvie com um clientRef novo |
lease_expired | O envio travou na última tentativa (por exemplo, num reinício); ele pode ter saído mesmo assim | Espere um eco ou um status do mesmo clientRef antes de reenviar |
not_on_whatsapp | O número não está no WhatsApp; não há novas tentativas | Corrija o número; verifique números antes de enviar |
reachout_timelocked | A conta está num bloqueio temporário de novas conversas; o envio foi recusado sem ser tentado | Reenvie depois do fim do bloqueio, com um clientRef novo |
curl -s "https://api.apiwpp.com/messages?q=pedido-1234" \
-H "Authorization: Bearer $API_KEY"O registro guarda, por padrão, os últimos 7 dias de mensagens, com o status (queued, sent, delivered, read, failed e, nas recebidas, received), o jobId, o clientRef, o messageId e o error de cada uma. A chave precisa do escopo logs:read.
Próximos passos
- Enviar mensagens: tipos de conteúdo, a fila e o que acontece depois do
202. - Webhooks e assinatura: receber, verificar e reprocessar os eventos.
- Limites de envio: por que um envio aceito espera na fila, e os três tipos de
429. - Referência: Enviar mensagem: todos os campos do corpo e as respostas.