Networks fail. If your request to send a message times out, you can't know whether it reached us — and retrying blindly could send the same WhatsApp message twice.
An idempotency key solves this: send a unique value in the Idempotency-Key header. If we've already seen that key, we return the original message instead of sending a new one.
curl https://api.waconnect.ai/v1/messages \
-H "Authorization: Bearer wc_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmation" \
-d '{"from":"+12125550147","to":"+14155550123","text":"Your order #1042 is confirmed"}'How it works#
- Supported on
POST /v1/messages. - The key is any string you choose, up to 255 characters. Something tied to the reason for the message works best:
order-1042-confirmation,appointment-77-reminder, or a UUID you store with the job. - Keys are scoped to your API key: two different API keys can use the same value without clashing.
- A repeated key returns the same message (same
id, currentstatus) and nothing is sent or charged again — even if two retries arrive at the same moment. - Keys are remembered for 24 hours. After that, the same key sends a new message.
- If the request was refused (for example
NOT_ON_WHATSAPP), the key isn't used up: you can retry with the same key after fixing the request.
To send another message with the same text, simply use a different key — a repeated key always means "the same request".