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.

PUT /v1/customer-flow/{flowId}/graph

JavaScript

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const response = await client.customerFlow.replaceGraph('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  graph: [{ type: 'AGENT_TURN' }],
});

console.log(response.data);

200

{
  "data": {
    "graph": [
      {
        "type": "AGENT_TURN",
        "nodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "ref": "<string>",
        "steps": "<array>",
        "mergeIntoNodeIds": [
          "<string>"
        ],
        "content": "<string>",
        "offScriptPolicy": {
          "reaction": "STAY_SILENT",
          "maxAttempts": 3,
          "then": "HANG_UP",
          "sayLine": "<string>",
          "waitSeconds": 300
        }
      }
    ],
    "variantsReshaped": true,
    "happyPath": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "precededByCustomerFlowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "precededByCustomerFlowVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "isGenerated": false,
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "personaOverride": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "language": "EN",
        "understoodLanguages": [
          "EN"
        ],
        "accent": "US",
        "age": "ADULT",
        "gender": "MALE",
        "backgroundNoise": "NONE",
        "speechPace": "NORMAL",
        "speechClarity": "CLEAR",
        "hasDisfluencies": false,
        "baseEmotion": "NEUTRAL",
        "intentClarity": "CLEAR",
        "confirmationStyle": "EXPLICIT",
        "memoryReliability": "HIGH",
        "responseTiming": "NORMAL",
        "idleMessages": [
          "<string>"
        ],
        "idleTimeoutSeconds": 10,
        "idleMessageMaxSpokenCount": 3,
        "idleMessageResetCountOnUserSpeechEnabled": true,
        "properties": {
          "age": 35,
          "zipCode": "94105",
          "occupation": "Software Engineer"
        },
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "displayName": "<string>",
        "description": "<string>",
        "secondaryLanguage": "EN",
        "backstoryPrompt": "A busy professional calling during lunch break"
      },
      "environment": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "backgroundNoise": "NONE",
        "backgroundNoiseVolume": 0.1,
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "description": "<string>"
      },
      "additionalExpectations": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "prompt": "<string>"
        }
      ],
      "type": "SCRIPTED",
      "steps": [
        {
          "type": "AGENT_TURN",
          "nodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "ref": "<string>",
          "steps": "<array>",
          "mergeIntoNodeIds": [
            "<string>"
          ],
          "content": "<string>",
          "offScriptPolicy": {
            "reaction": "STAY_SILENT",
            "maxAttempts": 3,
            "then": "HANG_UP",
            "sayLine": "<string>",
            "waitSeconds": 300
          }
        }
      ],
      "systemKey": "<string>"
    },
    "edgeCases": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "title": "<string>",
        "precededByCustomerFlowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "precededByCustomerFlowVariantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "isGenerated": false,
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "personaOverride": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "language": "EN",
          "understoodLanguages": [
            "EN"
          ],
          "accent": "US",
          "age": "ADULT",
          "gender": "MALE",
          "backgroundNoise": "NONE",
          "speechPace": "NORMAL",
          "speechClarity": "CLEAR",
          "hasDisfluencies": false,
          "baseEmotion": "NEUTRAL",
          "intentClarity": "CLEAR",
          "confirmationStyle": "EXPLICIT",
          "memoryReliability": "HIGH",
          "responseTiming": "NORMAL",
          "idleMessages": [
            "<string>"
          ],
          "idleTimeoutSeconds": 10,
          "idleMessageMaxSpokenCount": 3,
          "idleMessageResetCountOnUserSpeechEnabled": true,
          "properties": {
            "age": 35,
            "zipCode": "94105",
            "occupation": "Software Engineer"
          },
          "createdAt": "<string>",
          "updatedAt": "<string>",
          "displayName": "<string>",
          "description": "<string>",
          "secondaryLanguage": "EN",
          "backstoryPrompt": "A busy professional calling during lunch break"
        },
        "environment": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "backgroundNoise": "NONE",
          "backgroundNoiseVolume": 0.1,
          "createdAt": "<string>",
          "updatedAt": "<string>",
          "description": "<string>"
        },
        "additionalExpectations": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "prompt": "<string>"
          }
        ],
        "type": "SCRIPTED",
        "steps": [
          {
            "type": "AGENT_TURN",
            "nodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "ref": "<string>",
            "steps": "<array>",
            "mergeIntoNodeIds": [
              "<string>"
            ],
            "content": "<string>",
            "offScriptPolicy": {
              "reaction": "STAY_SILENT",
              "maxAttempts": 3,
              "then": "HANG_UP",
              "sayLine": "<string>",
              "waitSeconds": 300
            }
          }
        ],
        "systemKey": "<string>"
      }
    ],
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

flowId · string<uuid> · required

Body

application/json

graph · object[] · required

The complete graph. This replaces the flow's existing steps rather than merging into them.

Minimum array length: 1

One 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.

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.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Show child attributes

allowUnmerge · boolean

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

200

application/json

The flow graph after the write

data · object · required

Show child attributes