Studies

A study defines how the AI conducts interviews with your participants. It includes research goals, an interview script with segments, and configuration for how the AI should engage.

Creating a Study

Go to Studies -> Create Study. Add goals, then shape the interview with ordered Talk, Observe, and Speak segments. The block sequence defines whether the study is a conversation, task observation, or a mix.

Script Schema

Every study script must have version: 2, a goals array, and a segments array.

Field	Required	Type	Notes
`version`	yes	`2`	Must be exactly `2`
`goals`	yes	array	`[{ id, description }]` objects
`segments`	yes	array	Segment objects (see below)
`segments[].id`	yes	string	Unique within script
`segments[].mode`	yes	string	`talk` \| `speak` \| `observe`
`segments[].title`	yes	string	Display label
`segments[].speak_text`	yes for `speak`	string	Spoken text delivered by AI
`segments[].talk`	recommended for `talk`	object	`{ system_prompt?, goals? }`
`segments[].instruction`	required for `observe`	string	Task instruction shown to participant
`segments[].conductor_context`	required for `observe`	string	AI-only context for interpretation and later debrief

At least one of instruction or conductor_context is required for observe segments. Production scripts advance by deterministic criteria: max_duration_s, user Done / step_done, url:<substring>, action:<selector-or-pattern>, complete_segment for talk, or scripted speak completion.

Study Script

The script defines the structure of the interview. It has goals (what you want to learn) and segments (phases of the conversation).

Goals

Goals tell the AI what insights to pursue:

{
  "goals": [
    { "id": "g1", "description": "Understand the trigger that made them look for a solution" },
    { "id": "g2", "description": "Identify workarounds they use for scheduling" },
    { "id": "g3", "description": "Learn what would make them switch from their current tool" }
  ]
}

Good goals are specific and outcome-oriented. Avoid vague goals like "understand the user experience."

Segments

Segments define the phases of the interview and how the AI should engage in each one:

{
  "version": 2,
  "goals": [
    { "id": "g1", "description": "Understand friction in checkout" }
  ],
  "segments": [
    {
      "id": "intro",
      "mode": "speak",
      "title": "Introduction",
      "speak_text": "Thanks for joining. I'd like you to complete a purchase — just act naturally."
    },
    {
      "id": "observe-checkout",
      "mode": "observe",
      "title": "Complete a purchase",
      "instruction": "Please complete a purchase of any item.",
      "conductor_context": "Participant is completing checkout. Preserve hesitation on payment or shipping steps for the debrief.",
      "advance_when": "url:/confirmation",
      "max_duration_s": 420
    },
    {
      "id": "debrief",
      "mode": "talk",
      "title": "Discuss what happened",
      "talk": {
        "system_prompt": "Ask about moments of hesitation or confusion during checkout.",
        "goals": ["g1"]
      }
    },
    {
      "id": "thanks",
      "mode": "speak",
      "title": "Thanks",
      "speak_text": "Thanks for walking through that. We're done for now."
    }
  ]
}

Segment Modes

Each segment has a mode that controls how the AI interacts:

Mode	Behavior	Best For
`talk`	Natural voice conversation. AI asks questions, listens, follows up.	Discovery, rapport building, debrief
`speak`	AI delivers a scripted one-way transition message.	Intro, task setup, transitions, thanks
`observe`	AI silently captures product usage, speech, clicks, navigation, and snapshots.	Usability testing, task completion

The study script controls mode order. For usability feedback, the clean pattern is speak instructions -> observe silently -> talk debrief from observed context -> speak thanks/end.

Example Scripts

Talk Interview

{
  "version": 2,
  "goals": [
    { "id": "g1", "description": "Understand the trigger event" },
    { "id": "g2", "description": "Map the solution evaluation process" },
    { "id": "g3", "description": "Identify hiring and firing criteria" }
  ],
  "segments": [
    {
      "id": "rapport",
      "mode": "talk",
      "title": "Warm-up",
      "talk": { "system_prompt": "Build rapport. Ask about their role and recent context.", "goals": [] }
    },
    {
      "id": "trigger",
      "mode": "talk",
      "title": "What triggered the search",
      "talk": { "system_prompt": "Uncover the specific event that caused them to look for a solution.", "goals": ["g1"] }
    },
    {
      "id": "evaluation",
      "mode": "talk",
      "title": "How they evaluated options",
      "talk": { "system_prompt": "Explore what alternatives they considered and why.", "goals": ["g2"] }
    },
    {
      "id": "decision",
      "mode": "talk",
      "title": "What made them decide",
      "talk": { "system_prompt": "Identify the criteria that drove the final choice.", "goals": ["g3"] }
    },
    {
      "id": "wrapup",
      "mode": "talk",
      "title": "Wrap-up",
      "talk": { "system_prompt": "Confirm key insights and thank them.", "goals": [] }
    }
  ]
}

Usability Test

{
  "version": 2,
  "goals": [
    { "id": "g1", "description": "Identify friction points in checkout" },
    { "id": "g2", "description": "Measure task completion confidence" }
  ],
  "segments": [
    {
      "id": "intro",
      "mode": "speak",
      "title": "Explain the task",
      "speak_text": "Thanks for joining. I'd like you to complete a purchase on this site. Just act naturally — there are no wrong answers."
    },
    {
      "id": "task",
      "mode": "observe",
      "title": "Complete checkout",
      "instruction": "Please add an item to your cart and complete the checkout process.",
      "conductor_context": "Participant is completing checkout. Normal friction: choosing shipping options, entering payment. Preserve cart abandonment or visible hesitation for the debrief.",
      "advance_when": "url:/confirmation",
      "max_duration_s": 420
    },
    {
      "id": "debrief",
      "mode": "talk",
      "title": "Discuss experience",
      "talk": { "system_prompt": "Ask about moments of hesitation or confusion during checkout.", "goals": ["g1", "g2"] }
    },
    {
      "id": "thanks",
      "mode": "speak",
      "title": "Thanks",
      "speak_text": "Thanks for your feedback. That's everything for today."
    }
  ]
}

Mixed Methodology

{
  "version": 2,
  "goals": [
    { "id": "g1", "description": "Understand daily workflow" },
    { "id": "g2", "description": "Spot friction in key tasks" }
  ],
  "segments": [
    {
      "id": "context",
      "mode": "talk",
      "title": "Background & context",
      "talk": { "system_prompt": "Ask about their role, tools they use daily, and a recent example of the target workflow.", "goals": ["g1"] }
    },
    {
      "id": "demo",
      "mode": "observe",
      "title": "Show me how you do X",
      "instruction": "Please walk me through how you normally handle [this task] in your day-to-day work.",
      "conductor_context": "Participant is demonstrating their current workflow. Preserve tool-switching, workarounds, or moments of visible friction for debrief.",
      "max_duration_s": 420
    },
    {
      "id": "probe",
      "mode": "talk",
      "title": "Why did you do it that way?",
      "talk": { "system_prompt": "Probe the specific choices made during the demo. Why that tool? Why that sequence?", "goals": ["g2"] }
    },
    {
      "id": "task",
      "mode": "observe",
      "title": "Try the new flow",
      "instruction": "Now try the same task using [the new feature].",
      "conductor_context": "Participant is trying the new feature. Compare to their existing workflow from the demo during the debrief.",
      "max_duration_s": 420
    },
    {
      "id": "compare",
      "mode": "talk",
      "title": "Compare old vs new",
      "talk": { "system_prompt": "Ask how the new flow compares to their current approach. What would they keep or change?", "goals": ["g1", "g2"] }
    },
    {
      "id": "thanks",
      "mode": "speak",
      "title": "Thanks",
      "speak_text": "Thanks for showing your workflow and sharing your perspective."
    }
  ]
}

Linking an Intake

A study can be linked to an intake so that qualified participants automatically enter the right interview. Set the screener_id when creating the study, or link it from the intake settings.

When linked:

Qualified intake respondents are auto-assigned to the study
The widget loads the study script after qualification
Interview tracking connects the intake response to the interview

Settings

Additional study configuration:

Setting	Description
`allowed_selectors`	CSS selectors recorded for scripted host-action targeting
`allowed_origins`	URL origins allowed to run the conductor interview

Observe mode remains silent capture. Scripted highlight and scroll_to actions use the selectors in their action payloads; do not rely on allowed_selectors as widget-runtime enforcement for those actions. When allowed_origins is non-empty, include the embed origin that runs the widget. Scripted host navigation should stay on the current host origin; allowed_origins does not authorize cross-origin redirects.

Tips

Start simple. A 3-segment script (intro → core → wrapup) works well for most research.
Use observation for usability. Don't ask users to describe their experience — watch them have it.
Keep goals specific. "Understand why users churn" is better than "understand the user."
Mix modes for depth. Give scripted instructions, observe silently, then talk about what happened. The combination produces the richest evidence.
Test your script. Run an interview yourself before recruiting participants.