Request a human agent

POST 
/api/widget/handover

PUBLIC endpoint (anonymous visitors, NO staff auth). The visitor asks to be connected to a human ("talk to an agent"). Silences the AI bot for the visitor's OWN conversation (taken EXCLUSIVELY from the verified session token, never the client) and alerts agents asynchronously. Accepts no body — the only authority is the token and the reason is fixed server-side to visitor_request.

Idempotent: if the conversation is already in human hands it is a no-op. Returns 202 Accepted; the widget observes the resulting state (handover_pending, ai_active=false) via the realtime conversation.updated event or the next session resume.

Request

Responses

202

Handover requested (agents alerted asynchronously).

403

Missing / invalid / cross-tenant session token.

404

Unknown or missing widget_key, or the conversation is gone.

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.