WhatsApp Templates API

14. Idempotency

Public Developer API for Meta template lifecycle on Cloud WhatsApp accounts. Same Meta engine as the Washeej dashboard. Access requires explicit template scopes; Device/QR management is rejected. Provider Meta delete stays deferred.

1. Overview

2. Authentication & scopes

3. Account capabilities

4. Validate a template

5. Create and submit

6. List and inspect status

7. Sync

8. Edit

9. Delete

10. Send approved template

11. Status webhooks

12. Error codes

13. Rate limits

14. Idempotency

15. Migration from /templates/send

Where Idempotency-Key is required

Template create — POST /v1/templates (and external-api twin).
Template send — POST /v1/templates/send and POST /external-api/templates/send (durable send idempotency).
Template / provider delete — when delete is enabled under policy; provider Meta delete remains fail-closed outside dedicated UAT.

Legacy POST /external-api/inbox/send-template-message does not require the header.

Behavior

Namespace: send keys are namespaced per credential/operation so they do not collide with create/delete keys; v1 and external-api share the send operation namespace.
Request fingerprint: hash of the send payload fields that define the operation; stored with the key.
Replay: same key + same fingerprint → original persisted HTTP result (provider_calls=0 on replay).
Payload mismatch: same key + different fingerprint → 409 idempotency_conflict (reason=payload_mismatch).
In-flight: concurrent same key → 409 idempotency_in_flight (retryable=true).
Provider outcome unknown: ambiguous transport after a possible Meta accept → recorded as provider_outcome_unknown; clients must not assume a safe blind resend.
Retention: keys expire after 1440 minutes (24h) from the durable store.
Safe retry: retry with the same key and payload after network failure; use a new key only for a new logical send.