Create a customer flow

Creates a customer flow. A SCRIPTED flow carries a step graph and gets one way of running it per path through the graph; an IMPROV flow carries the briefs you send. Customer flows replace the older simulation scenarios, so build a flow for anything new.

POST /v1/customer-flow

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 customerFlow = await client.customerFlow.create({
  graph: [{ type: 'AGENT_TURN' }],
  title: 'Reschedule an appointment',
  type: 'SCRIPTED',
});

console.log(customerFlow.data);

201

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "source": "CUSTOM",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "agents": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "description": "<string>",
        "customId": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>"
      }
    ],
    "agentExpectations": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "prompt": "<string>"
      }
    ],
    "type": "SCRIPTED",
    "scriptAdherence": "LOOSE",
    "offScriptPolicy": {
      "reaction": "STAY_SILENT",
      "maxAttempts": 3,
      "then": "HANG_UP",
      "sayLine": "<string>",
      "waitSeconds": 300
    },
    "branchingMode": "DETERMINISTIC",
    "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>"
      }
    ],
    "description": "<string>",
    "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
        }
      }
    ]
  }
}

Authorizations

Authorization · string · header · required

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

Body

application/json

Scripted

Improv

Input for creating a customer flow. SCRIPTED writes the conversation out as a graph of turns; IMPROV gives the simulated customer a brief and lets it improvise.

type · string · required

Allowed value: "SCRIPTED"

title · string · required

Minimum string length: 1

Example:

"Reschedule an appointment"

graph · object[] · required

The conversation, as a graph of steps. At most 100 steps across at most 25 paths. The variants come from the graph: one per path, so they are not sent here. A CUSTOMER_TURN describes what the simulated customer says and the persona phrases it; a CUSTOMER_VERBATIM_TURN is said word for word.

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

description · string | null

agentExpectations · object[]

Show child attributes

agentIds · string<uuid>[]

Agents this flow exercises. Optional for scripted flows.

scriptAdherence · enum<string>

How closely a run follows the script. LOOSE (default) hands the whole script to the simulated customer as one prompt; it keeps the call moving whatever your agent says. STRICT runs the script as a state machine on the agent service: at every agent step the simulated customer waits, silent, until your agent has said the expected line, and only then moves on. Scripted flows only; STRICT needs the agent-service transport and is not available on realtime models. (LOOSE is the default.)

Available options: LOOSE, STRICT

offScriptPolicy · object | null

STRICT only. What the simulated customer does when your agent does not say the expected line. Each unmatched agent utterance is an attempt: reaction runs per attempt (STAY_SILENT, REPEAT its last scripted line, RESPOND once in character without moving on, or SAY sayLine), and then runs when attempts reach maxAttempts or your agent stays silent for waitSeconds (HANG_UP ends the call with ended reason SCRIPT_DIVERGED, HANG_UP_INVALIDATE ends it the same way and invalidates the run so it is scored by nothing and counted nowhere, MOVE_ON advances anyway, ADAPT hands the rest of the call to loose behaviour). Null: stay silent, 3 attempts, hang up. The default for every agent step; an AGENT_TURN step can carry its own.

Show child attributes

branchingMode · enum<string>

How a run walks the graph. DETERMINISTIC ("Simulate every path" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE ("Adapt to your agent") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade. (DETERMINISTIC is the default.)

Available options: DETERMINISTIC, ADAPTIVE

Response

201

application/json

The created customer flow

data · Scripted · object · required

The conversation a simulated customer has with the agent under test.

Scripted

Improv

Voicemail

Show child attributes