Advance a deterministic flow

POST 
/api/widget/flow/postback

PUBLIC endpoint (anonymous visitors, NO staff auth). The visitor advances a deterministic conversation flow by clicking one of the buttons the bot offered. The tenant is resolved from the widget_key and the conversation comes EXCLUSIVELY from the verified session token — a visitor can only ever advance their OWN flow.

SERVER-VALIDATED selection: the posted value is honoured only if it matches an option of the node the conversation is currently sitting on. An unknown / forged value, a stale node_key (race / double-click guard), or a flow that is not running advances nothing and returns 422 — the visitor cannot inject an arbitrary block or jump to an arbitrary node.

On success the runner emits the next node's bot message (delivered to the widget via the visitor-safe realtime broadcast, never the staff channel) and may resolve a terminal action (hand to AI / hand to a human / end). Returns 202 Accepted; the widget observes the new message via realtime or the next history fetch.

Request

Responses

202

Flow advanced; the next bot message was emitted.

403

Missing / invalid / cross-tenant session token.

404

Unknown or missing widget_key, or the conversation is gone.

422

The request failed validation.

429

Rate limit exceeded.

Response Headers

X-RateLimit-Limit

Request quota for the current window.

X-RateLimit-Remaining

Remaining requests in the current window.

Retry-After

Seconds to wait before retrying.