Idempotency
Safely retry message creation using Idempotency-Key headers.
Why idempotency
Network retries or client restarts can cause duplicate message requests. Use an Idempotency-Key header to ensure only one message is created.
How it works
- Send a unique key per logical message attempt
- If the same key is received again, the original message is returned with 200
- New unique keys create a new message and return 202
Example
curl -X POST 'https://backend.blooio.com/v2/api/chats/%2B15551234567/messages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: checkout-1234' \
-d '{ "text": "Thanks!" }'First response (202):
{ "message_id": "Qm8FhbH3P7R", "status": "queued" }Retry with same key (200):
{ "message_id": "Qm8FhbH3P7R", "status": "queued" }Best practices
- Use a collision-resistant identifier (UUID v4)
- Scope keys to your business action (e.g., order id)
- Expire keys on the client side to avoid unbounded storage
import { randomUUID } from 'node:crypto'
import fetch from 'node-fetch'
const chatId = encodeURIComponent('+15551234567')
const idempotencyKey = `order-${randomUUID()}`
const res = await fetch(`https://backend.blooio.com/v2/api/chats/${chatId}/messages`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.BLOOIO_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey
},
body: JSON.stringify({ text: 'Order confirmed' })
})
const data = await res.json()import os, uuid, requests
from urllib.parse import quote
chat_id = quote('+15551234567', safe='')
res = requests.post(f'https://backend.blooio.com/v2/api/chats/{chat_id}/messages',
headers={
'Authorization': f"Bearer {os.environ['BLOOIO_API_KEY']}",
'Content-Type': 'application/json',
'Idempotency-Key': f"order-{uuid.uuid4()}"
},
json={ 'text': 'Order confirmed' }
)
data = res.json()