Skip to main content
Variables let you reuse the same customer flow with different data on every run. Instead of hardcoding details into a flow’s brief or steps, you write {{variableName}} placeholders that get replaced with real values at runtime. Variables show up in three places:
  1. On a flow variant — key/value entries the simulator hands to the customer-side model, so the simulated customer can answer the agent’s questions consistently
  2. On a run plan — named variables with a type and an optional default, referenced as {{name}}, with per-attachment overrides when you attach flows
  3. At runtime — a modal collects any values that still need filling in before the run starts

​
1. Variables on a flow variant

Each variant of a customer flow carries its own set of variables — key/value entries like name, account_id, or last_visit that the simulator gives to the customer-side model. When the agent asks “Can I get your account number?”, the simulated customer answers with the value you set, consistently, every run.

​
Editing variant variables

Open the variant and click the Variables chip (next to the Persona and Environment chips). From there you can:
  • Add variable — add a key/value row inline
  • Apply a test profile — replace the variant’s entries with a saved test profile’s properties in one click

​
{{variable}} autocomplete

Text fields in the flow editor — the customer setup brief in Improv mode, step text in Scripted mode — support {{variable}} tokens with autocomplete sourced from your project’s property definitions:
  • {{name}} — flow-scoped properties, resolved from the variant’s variables
  • {{persona.name}} — persona-scoped properties, resolved from the variant’s persona
Type {{ to open the autocomplete and pick a property, or keep typing to reference a new one.

​
2. Variables on a run plan

Run plans define their own variables in the Advanced section of the create-run page. Each run-plan variable has:
FieldDescription
NameReferenced as {{name}} in attached flows
TypeThe value type (string, number, boolean, date)
DefaultOptional. If omitted, the value must be provided before each run
Variables with defaults let a plan run unattended — on a schedule or from the API — without prompting anyone. Variables without defaults turn the plan into a parameterized suite: every run asks for fresh values.

​
Per-attachment overrides

When you attach customer flows to a plan via the Attach flows picker, each attachment can override {{variable}} values for that flow. Overrides win over the values stored on the variant, so you can attach the same flow with different data — for example, one attachment with appointmentType: urgent and another with appointmentType: routine checkup — and each becomes its own set of test calls.

​
3. Providing values at runtime

If any variable lacks a value when you start a run — Run now, ⌘↵, or a “Fresh run” re-run — a modal collects the missing values first. It gathers, in one place:
  • Run-plan variables without defaults
  • Flow variant values — per-variant values for attached scripted flows
  • Persona property values — values for {{persona.*}} references, which persist onto the persona for future runs
Once every required value is filled in, the run starts.
“Re-run with same data” replays a run’s exact captured snapshot, so it never prompts for variables. “Fresh run” builds new test calls from the plan as configured today and collects unresolved variables first.

​
Reserved variables

Some variable names are reserved for system use and resolved automatically:
VariableResolves to
{{persona.*}}Properties of the variant’s persona (e.g. {{persona.name}})
{{phoneNumberToDial}}The phone number to dial for outbound simulations
{{simulationJobId}}The current simulation job’s ID
Don’t define your own variables with these names.

​
Setting variables via the API

The REST API keeps the older naming: flows are passed in a scenarios field, and runtime overrides are keyed by scenarioId.

​
Pre-set variables when creating a plan

Add a variables object to each entry in scenarios when creating a run plan. The same flow ID can appear multiple times with different values — each entry becomes a separate test case:
POST /v1/simulation/plan
{
  "name": "Patient Scheduling - Multi Profile",
  "direction": "INBOUND",
  "iterationCount": 2,
  "maxSimulationDurationSeconds": 300,
  "scenarios": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "variables": {
        "patientName": "John Doe",
        "appointmentType": "urgent",
        "insuranceProvider": "Aetna"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "variables": {
        "patientName": "Jane Smith",
        "appointmentType": "routine checkup",
        "insuranceProvider": "Blue Cross"
      }
    }
  ],
  "personas": [{ "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }],
  "agentEndpoints": [{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }],
  "metrics": [{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
  "autoRun": false
}

​
Override variables when triggering a run

Runtime values are passed in the request body when triggering a job. They override any values stored on the plan. Global format — the same values apply to every flow in the plan:
POST /v1/simulation/plan/:planId/job
{
  "variables": {
    "orderNumber": "12345",
    "environment": "staging"
  }
}
Per-flow format — different values per flow, keyed by scenarioId:
POST /v1/simulation/plan/:planId/job
{
  "variables": [
    {
      "scenarioId": "550e8400-e29b-41d4-a716-446655440000",
      "variables": {
        "orderNumber": "12345",
        "claimType": "damaged item"
      }
    },
    {
      "scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e",
      "variables": {
        "orderNumber": "67890",
        "claimType": "missing package"
      }
    }
  ]
}
If everything has a stored value or default, the body is optional — POST /v1/simulation/plan/:planId/job with no body starts the run as configured.

Customer Flows

Author the flows and variants that variables plug into

Run Plans

Compose flows, personas, metrics, and variables into a reusable suite

Running Simulations

Trigger runs and follow them live

Personas

The customer identities behind values