Idempotency

Network retries are a fact of life. Idempotency lets you retry a send without WhatsApp receiving two copies.

How it works today

On POST /v1/channels/{id}/messages, supply a stable client_ref field in the body:

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

The response echoes it:

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

If you POST again with the same client_ref within the de-duplication window (currently a few minutes), we return the original message_id and do NOT re-send. If the window has elapsed and the original send still hasn't surfaced as message.sent via webhook, the second call WILL re-send — by then the platform considers the original lost.

Choosing a client_ref

• Pick something idempotent by construction. E.g. order-1234-confirmation, not Date.now().
• Scope it to your retry window. A client_ref that you've forgotten about before retrying defeats the purpose.
• Don't reuse across logically-different sends. Reusing means the second send is dropped silently.

Idempotency-Key header (roadmap)

The Stripe/Resend-style Idempotency-Key header is on our roadmap (P1 in WhatsApp gap map). When it ships:

• Header-based idempotency will apply to ALL mutating routes, not just message sends.
• The de-dup window will be configurable per-call up to 24 hours.
• The body's client_ref will remain for message-specific correlation (analytics, dashboards).

Today the body field is enough for the common case (outbound message retry).