Idempotência

Retentativas de rede fazem parte da vida. A idempotência permite que você reenvie uma mensagem sem que o WhatsApp receba duas cópias.

Como funciona hoje

No POST /v1/channels/{id}/messages, informe um campo client_ref estável no corpo:

{
  "type": "text",
  "to": "+15551234567",
  "text": "Order #1234 confirmed",
  "client_ref": "order-1234-confirmation"
}

A resposta o devolve:

{
  "message_id": "msg_01J...",
  "client_ref": "order-1234-confirmation",
  "status": "sent"
}

Se você fizer o POST de novo com o mesmo client_ref dentro da janela de desduplicação (atualmente alguns minutos), devolvemos o message_id original e NÃO reenviamos. Se a janela já passou e a mensagem original ainda não apareceu como message.sent via webhook, a segunda chamada VAI reenviar — a essa altura a plataforma considera a original perdida.

Escolhendo um client_ref

• Escolha algo idempotente por construção. Ex.: order-1234-confirmation, não Date.now().
• Limite ao seu período de retentativa. Um client_ref que você já esqueceu antes de reenviar derrota o propósito.
• Não reutilize entre envios logicamente diferentes. Reutilizar significa que o segundo envio é descartado silenciosamente.

Header Idempotency-Key (roadmap)

O header Idempotency-Key no estilo Stripe/Resend está no nosso roadmap (P1 no mapa de lacunas do WhatsApp). Quando chegar:

• A idempotência baseada em header valerá para TODAS as rotas que modificam dados, não só os envios de mensagens.
• A janela de desduplicação será configurável por chamada, até 24 horas.
• O client_ref do corpo continuará existindo para correlação específica de mensagens (analytics, dashboards).

Hoje o campo do corpo já basta para o caso comum (retentativa de mensagem de saída).