Pular para o conteúdo

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.

Ver em Markdown

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:

  1. torna o envio idempotente: repetir a requisição não duplica a mensagem;
  2. 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 clientRef numa conexão enfileira a mensagem 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 enfileira nada.
bashEnviar com clientRef
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"}'
202
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }

A mesma requisição, repetida:

200
{ "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 clientRef fica 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:

RespostaO que quer dizer
200 com duplicate: trueUm envio anterior com esse clientRef foi aceito. Nada novo foi enfileirado
202Nenhum envio anterior foi aceito; este foi, agora
400, 404 ou 429 de cota (com X-Usage-Percent) ou new_recipient_cap_reachedNenhuma requisição com esse clientRef foi aceita: nada foi enfileirado
429 com Retry-After, sem X-Usage-Percent nem error de destinatários novosLimite de requisições: a repetição nem chegou a ser examinada. Espere e repita
401, 403 ou 402A 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-AfterA 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',
})

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:

EventoQuando
message.outgoingA mensagem saiu, com origin: API (só para projetos com emitOutgoing: true)
message.deliveryCada mudança de status (sent, delivered, read, failed), junto com o messageId do WhatsApp
message.send_failedA apiwpp desistiu do envio; messageId é null e reason diz por quê
jsonmessage.delivery
{
  "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.

jsonmessage.send_failed
{
  "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:

reasonO que houveO que fazer
attempts_exhaustedTodas as tentativas de envio falharamConfira a conexão e reenvie com um clientRef novo
lease_expiredO envio travou na última tentativa (por exemplo, num reinício); ele pode ter saído mesmo assimEspere um eco ou um status do mesmo clientRef antes de reenviar
not_on_whatsappO número não está no WhatsApp; não há novas tentativasCorrija o número; verifique números antes de enviar
reachout_timelockedA conta está num bloqueio temporário de novas conversas; o envio foi recusado sem ser tentadoReenvie depois do fim do bloqueio, com um clientRef novo
bashConciliar pelo registro de mensagens
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

Esta página ajudou? · Atualizado em 29 set 2026