Idempotency

A client that retries a send after a timeout or a 5xx cannot know whether the first attempt reached WhatsApp. Without idempotency the only safe policy is to not retry — which means dropping legitimate replies on any transient fault.

Send an Idempotency-Key header and the retry becomes safe.

curl -X POST https://api.splashifypro.com/api/v1/app/messages/send-text \
  -H "Authorization: Bearer oc_live_…" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9f4b-2c1d9a3e77b0" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "text": "Your invoice is ready."}'

Repeat that exact request and the cached response is replayed — no second message is sent.

Where it applies

Every send endpoint, i.e. the routes where a retry can duplicate a real customer-visible message:

POST /api/v1/app/messages/send-text
POST /api/v1/app/messages/send-media
POST /api/v1/app/messages/send-template
POST /api/v1/app/messages/send-location
POST /api/v1/app/messages/send-contact
POST /api/v1/app/messages/send-reaction
POST /api/v1/app/messages/send-interactive
POST /api/v1/app/messages/send-flow
POST /api/v1/public/sms/send
POST /api/v1/public/sms/send-bulk

On the two SMS endpoints a replay also has "replayed": true in the body, and a bulk replay carries the send's status as it is now. See Send SMS and Send bulk SMS.

Behaviour

Situation	Result
No `Idempotency-Key` header	Request proceeds normally, nothing cached
First request with a key	Executed; a `2xx` response is cached for 24 hours
Repeat with the same key and same body	Cached response replayed, `Idempotency-Replayed: true`
Repeat while the first is still running	`409` `idempotency_in_progress`
Same key, different body	`422` `idempotency_key_reused`
First request returned non-`2xx`	Not cached — the key is released and stays retryable

Confirming it took effect

Every response to a request carrying the header includes Idempotency-Replayed, set to false on the original and true on a replay. You never have to infer whether the header was honoured.

Reusing a key for different content

Returning 422 here is deliberate. Silently replaying the first response would make the second, different message vanish while reporting success — a far worse outcome than an explicit error. Generate a fresh key per distinct message; a UUID per outbound message works well.

If our cache is unavailable

Idempotency fails open: if the store is unreachable the send proceeds unprotected rather than being refused. A cache outage should not become a messaging outage. This is the one case where a duplicate remains possible.

Why this matters more with interactive messages

A duplicated text message is noise. A duplicated approval prompt invites someone to approve the same thing twice. If you send interactive messages, use an idempotency key.

Choosing a key

Must be unique per distinct message; up to 255 characters.
Keys are scoped to your account and the endpoint, so the same string on send-text and send-media are different operations and never collide.
A natural choice is a UUID generated when you decide to send — reuse that same value across every retry of that decision.