Scenario Studio

The scenario is the product: a versioned document describing the whole conversation, edited on a drag-and-drop canvas and executed node by node for every call.

Two editors, one rule

• v2 canvas (/scenarios/{id}/v2) — the primary designer: seventeen node types, retry lanes, sub-flows, global handlers, undo/redo, node templates.
• v1 editor (/scenarios/{id}) — kept so old documents stay readable. Nothing is migrated behind your back: Convert to v2 is explicit, saves the translation as a new version, and leaves the v1 history untouched (ADR-0019).

The list opens each scenario in the editor its latest version belongs to. New scenarios start in the v2 canvas.

The edit lock

Opening a scenario takes the edit lock (ADR-0042). If somebody else holds it, the canvas opens read-only with a banner naming them — a studio admin can take over. The lock heartbeats while your tab is open and is a precondition on every save: a save without it answers 409 and the studio tells you who has it now, instead of losing your changes silently.

Designing on the canvas

• Add nodes from the toolbar palette (grouped: Conversation, Understanding, Logic, Integration, Ending) or drag them onto the canvas. Node templates from the library insert a configured node in one click.
• Wire rules by dragging from a node's handle to the next node. Each rule has two lanes: next advances the flow; retry re-enters the same node (timeouts, unfinished answers), bounded by Re-prompts allowed and Times this node may run.
• The property panel edits the selected node: prompts, capture options (DTMF/speech, timeouts, barge-in), slots to fill, LLM options, and every rule — cases, variable conditions, operator, and where it goes.
• Sub-flows are tabs across the header: MAIN plus every sub-scenario; a SCENARIO_CALL node runs one and comes back. Global handlers (error, hangup) live beside every flow's canvas.
• Annotations — Group and Memo — are canvas-only geometry: they round-trip through save and never affect execution.
• Shortcuts: Ctrl+S save · Ctrl+Z / Ctrl+Shift+Z undo/redo · Ctrl+D duplicate · Del delete · Esc deselect.

The seventeen node types

Group	Types	Notes
Conversation	BEGIN · GUIDE (Say) · DIALOGUE (Ask)	DIALOGUE speaks, listens, and fills slots
Understanding	NLU · LLM · LLM_PLUS	model turns — classify, extract, or reason in rounds
Logic	BRANCH · FORK · JOIN · TAG · PERSIST · SCENARIO_CALL · RETURN	BRANCH routes on variable conditions
Integration	API	runs a definition from the project library; the api holds the credential
Ending	TRANSFER · CLOSING · END	TRANSFER hands the caller to a 3CX agent

Validate, save, publish

Validate runs the api's checks and pins every finding to the node it is about (unreachable node, empty prompt, rule going nowhere). Save creates an immutable new version — the api refuses invalid documents, so the studio validates first and shows you the findings instead of a generic error. Publish puts the latest version live for new calls; it is always a separate, explicit step.

History lists every version: preview any v2 version read-only, or Restore — which appends that snapshot as a new latest version. History is never rewritten.

Variables

Declared per scenario, filled from contact columns (campaigns), caller input (slots), or API results, and rendered into prompts as . The left panel shows where each variable is used.