Idempotency
Retry a send without fear of messaging the same person twice.
How it works
Add an Idempotency-Key header — any unique string up to 255 characters, typically a UUID — to a send request. Engage stores the successful result of the first request with that key for 24 hours. Repeating the request with the same key and the same body returns the original response without sending again.
The header is honoured on the three endpoints that send messages:
POST /v1/messagesPOST /v1/messages/bulkPOST /v1/conversations/{id}/messages
Other endpoints ignore it. Creating a contact twice returns 409 conflict, so those calls are already safe to retry.
curl https://engage.swastik.ai/v1/messages \
-H "Authorization: Bearer $ENGAGE_API_KEY" \
-H "Idempotency-Key: 5d2c8f0e-4b6a-4f7e-9c1d-2a3b4c5d6e7f" \
-H "Content-Type: application/json" \
-d '{"to":"+14155550101","type":"text","text":{"body":"Your OTP is 482913"}}'Rules
- Keys are scoped to the API key that sent them — two different API keys can use the same value without clashing.
- Reusing a key with a different request body returns
422 validation_failed. - If the first request is still in progress, a concurrent retry receives
409 conflict; retry shortly after. - Only successful responses are stored. If the first attempt fails (any
4xxor5xx), the key is released — fix the request if needed and retry with the same key. - Keys longer than 255 characters are rejected with
422.
Client references
Messages also accept a client_ref field — your own identifier (for example an order id). Up to 128 characters. It is stored on the message and returned by GET /v1/messages/{id}. Status webhooks identify the message by its Engage id, so keep the id from the send response next to your own reference.
order-48213-shipped — so retries after a process crash still deduplicate.