Safe writes and retries

The Gateway supports a small set of reviewed writes. Each one needs an Idempotency-Key, so a retry never repeats an effect. Event subscription changes are the exception: their key is optional.

Operation	Effect
Add a visitor note	Adds a note on the visitor’s newest stored conversation.
Set a conversation disposition	Sets a configured disposition on a stored conversation.
Run an AI feature	Runs a configured AI feature on supplied text. Only offline language detection is supported today.
Preview a configuration change	Previews an AI feature name or enabled change. Nothing is saved.

Note and disposition writes are attributed to a native operator, so the application needs an author mapping for that website.

Send a write

Use a key of 1 to 128 visible ASCII characters that’s unique to the change you intend.

curl -s -X POST "$GATEWAY/api/v1/visitors/vis_4927_123_42/notes" \
  -H "Authorization: Bearer $INSIDE_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-note-2026-10-13-0001" \
  -d '{"text":"Customer asked for a callback on Friday."}'

Retry safely

When retrying, send the same key and the same body. A completed write returns its original result without acting twice.
Results are kept for 24 hours. After that, the same key still can’t create a new effect.
Never generate a new key automatically after an unknown outcome. That can repeat the change.

Conflicts

Writes return 409 with one of these codes:

Code	Meaning	What to do
`idempotency_conflict`	The key was used with a different body or different permissions.	Use the original body, or a new key for a genuinely new change.
`operation_in_progress`	The same command is still pending.	Wait, then retry with the same key.
`operation_conflict`	The website rejected the change.	Check the input, for example that the disposition is configured.
`outcome_unknown`	The result is uncertain.	Retry with the same key, or check the receipt.

Check a receipt

Successful and 409 write responses can include an X-Gateway-Operation-Id: op_... header. Read its status with the same credential:

curl -s "$GATEWAY/api/v1/operations/op_...?website_id=web_4927_123" \
  -H "Authorization: Bearer $INSIDE_GATEWAY_TOKEN"

The status is pending, acknowledged or outcome_unknown. acknowledged means the Gateway recorded the website’s reply. It doesn’t prove business success or delivery.

Event subscriptions

Subscription create, replace and delete accept an optional Idempotency-Key. With a key, the same input reuses the original result for 24 hours. Without one, each request is a new effect. See event pull subscriptions.