handoff_settings

Auto-escalation rules that hand a conversation to a human channel based on keywords or consecutive unresolved turns.

handoff_settings — Handoff settings

Auto-escalation rules that hand a conversation to a human channel based on keywords or consecutive unresolved turns.

Section key handoff_settings · Shape object · Tier Pro and up (free trial includes it)
Edit in the dashboard: Human handoff page
Related: Handoff guide

Fields

Field	Required	Type	Allowed values / constraints	Default	Description
auto_escalation	no	object	—	—	Automatic escalation trigger configuration. Item fields below.
required_inbound	no	array of object	max 20 items	—	Fields a calling agent MUST supply when handing off TO this agent (its inbound-input contract). The caller fills them via handoff_request’s provided_input; the values arrive in the handoff envelope. Enforced as a BLOCKING gate before this agent starts: a sibling handoff missing a required field is rejected back to the caller, and an external A2A handoff parks in input-required with this schema. Same field shape as a handoff expected_return contract, but the opposite direction. Item fields below.

auto_escalation fields

Automatic escalation trigger configuration.

Field	Required	Type	Allowed values / constraints	Default	Description
enabled	no	boolean	—	—	Master switch for auto-escalation rules.
rules	no	array of object	—	—	Ordered list of escalation rules. First matching rule wins. Item fields below.

required_inbound items

Fields a calling agent MUST supply when handing off TO this agent (its inbound-input contract). The caller fills them via handoff_request’s provided_input; the values arrive in the handoff envelope. Enforced as a BLOCKING gate before this agent starts: a sibling handoff missing a required field is rejected back to the caller, and an external A2A handoff parks in input-required with this schema. Same field shape as a handoff expected_return contract, but the opposite direction.

Field	Required	Type	Allowed values / constraints	Default	Description
name	yes	string	—	—	Machine identifier (letters/digits/underscores) — the key the caller puts in provided_input.
type	yes	enum	one of string, multiline, number, boolean, enum, date, url	—	Field type — drives value coercion and validation.
label	no	string	—	—	Human-readable label. Defaults to name.
description	no	string	—	—	What this field is for — shown to the calling agent.
required	no	boolean	—	—	When true, the handoff is BLOCKED until the caller supplies this field.
enum_values	no	array of string	—	—	For type=‘enum’: the allowed values.
placeholder	no	string	—	—	Example value shown to the caller.

auto_escalation.rules items

Ordered list of escalation rules. First matching rule wins.

Field	Required	Type	Allowed values / constraints	Default	Description
trigger	yes	enum	one of keyword, consecutive_unresolved_turns	—	What causes this rule to fire.
channel_id	yes	string	—	—	ID of the handoff_channel row to route to when this rule fires.
patterns	no	array of string	—	—	For trigger=‘keyword’: list of keywords/phrases that trigger escalation.
threshold	no	integer	—	—	For trigger=‘consecutive_unresolved_turns’: number of unresolved turns before escalating.
enabled	no	boolean	—	—	Whether this rule is active. Missing or true = active; false = skipped at evaluation time.