Handoff conversation from AI to a human
Distinct from /assign: clears any AI agent assignment, flips status to pending so the conversation re-enters the unassigned queue, and stamps metadata.needs_human + handoff_reason + target_queue + handoff_skill_tags + handoff_matched_operators so the receiving human picks up the context. Audit #HANDOFF-1 also persists a top-level handoff_brief (LLM-generated 2-3 sentence summary) and handoff_reason_category (machine-readable enum) on the conversation row, and audit #HANDOFF-2 enqueues the conversation in the org’s Redis sorted-set queue so the customer-facing widget can render queue position.
Authorizations
Dashboard JWT token from Clerk
Path Parameters
Body
Short reason — surfaced to the receiving human (e.g. 'asked for a manager').
500Optional queue to route to. Defaults to the tenant's default queue.
100Machine-readable handoff category for analytics. When omitted, inferred from the free-text reason.
cant_understand, policy_block, customer_request, tool_failed, escalation_threshold, manual Caller override for the skill set used to match operators. When omitted, derived from the conversation's most recent AI agent's skill_tags.
2040Caller-supplied 2-3 sentence summary. When omitted, the service generates one via the LLM gateway.
600Response
Default Response