Replace a scripted flow's steps
Replaces a scripted flow’s conversation graph with the tree you send. This is a full replace, not a merge: a step you omit is removed.
Include nodeId on a step to update the existing one, omit it to create a new step. Where two branches
rejoin, keep the mergeIntoNodeIds references a read gave you. Dropping them un-merges those branches
and is refused unless allowUnmerge is set.
A change to the set of paths re-seeds how the flow runs, which the response reports as
variantsReshaped along with the resulting happy path and edge cases.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
The complete graph. This replaces the flow's existing steps rather than merging into them.
1One step in a scripted flow's conversation.
nodeId is the identity contract: include it to update the existing step, omit it to create a new one.
A step continues into steps (more than one child is a branch point) and/or mergeIntoNodeIds, which
names steps elsewhere in the same request that this step rejoins. Branches that come back together are
represented that way rather than by repeating the shared step, so reading a flow, editing it and writing
it back preserves it exactly.
A merge target is named by its nodeId when it already exists, or by ref when it is being created in
the same request. ref is a label you choose, it is request-local, and it is never stored or returned.
Put the shared step inline under the first branch that reaches it and point the others at it: a top-level
step is a root wired straight from the start of the flow, so a merge target parked there would also be
reachable directly.
A CUSTOMER_TURN describes what the simulated customer says and the persona phrases it; a
CUSTOMER_VERBATIM_TURN is said word for word, and one placed as a top-level step opens the call
the moment it connects, before the agent speaks. CUSTOMER_FIRST_MESSAGE is the retired name for
that opening case: still accepted, stored and returned as CUSTOMER_VERBATIM_TURN.
The two DTMF types are mirror images and both require dtmfDigits. CUSTOMER_DTMF is keys the
simulated caller presses while navigating your agent. AGENT_DTMF is keys your agent under test is
expected to press while navigating a menu the simulation is playing, so its digits are an assertion the
run is graded against rather than an instruction, and it counts as an agent turn for role alternation.
A CUSTOMER_HANDOFF hands the phone to another persona (handoffPersonaId), or back to the flow's
own persona when it is null. The steps after it are spoken by whoever holds the phone. It sits between
turns like a silence, so it may follow either side.
In a STRICT flow an AGENT_TURN may carry its own offScriptPolicy, which replaces the flow-level one at
that step. Omit it (or send null) to follow the flow's policy. Use it where one missed step makes the rest
of the call meaningless: an authentication menu, say, with then: HANG_UP_INVALIDATE.
Any step may set stage, the named phase of the flow it belongs to: the IVR, the login, the scenario
itself. Steps in one stage are drawn as a group in the editor, and the name is yours: the reports say it
back to you. The stage does not have to exist first, it is created the first time a step names it, and a
name already in the project is matched ignoring case.
A stage with required: true is a gate. A run that ends without getting PAST it never reached what was
being measured, so it stays in the report, labelled with the stage it never completed and the one it
stopped in, and is left out of the run score and the success-criteria verdict: an agent that never clears
the IVR does not fail every check in a scenario it never started. required belongs to the stage rather
than to the step, so a read returns it on every step in that stage, and a write that sets it on any one
of them marks the whole stage. A flow that requires no stage is scored exactly as before.
A stage with analyze: false is not measured. Its turns are kept out of the core call metrics (talk
time, speech pace, turn and response timings), which is what an IVR usually wants alongside
required: true: the run has to get through the menu, but how the agent sounded reading it is not what
is being tested. Coverage is being extended package by package, so the judged metrics (quality,
compliance, repetition, escalation, tone) still read the whole call for now. Nothing is cut and nothing
is re-timed, so a turn at 4:10 is still at 4:10 with an earlier stage excluded, and rate metrics divide
by the part of the call that was measured rather than by the whole of it. Defaults to true, belongs to
the stage the same way required does, and turning it off on any one step turns it off for the stage.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
Confirms a write that drops branches which currently rejoin. Only needed when the request omits mergeIntoNodeIds references the flow already had; a faithful round trip never needs it.
Response
The flow graph after the write