VoiceFlow Studio Features

The VoiceFlow studio gives you fine-grained control over every stage of a call. This page covers the advanced fields you can configure on each node in the canvas, what they actually do during a live call, and when to use each one. For the basics of creating a VoiceFlow, see VoiceFlows. This guide assumes you already have a flow and want to tune it.

How a stage runs

A VoiceFlow is a graph of stages. During a live call, the runtime is always “in” exactly one stage. The agent’s behavior in that stage is shaped by:

The stage instructions — the system prompt for the conversation LLM.
Outcomes — what the agent listens for; firing one transitions the call to a new stage.
Optional advanced fields — described below. Most flows don’t need every one.

Click any node on the canvas to open the Properties Panel on the right. That’s where you configure everything below.

Stage instructions

The most important field. This is the system prompt your agent reads while in this stage. Write it like you’d brief a human colleague: who they are, what to do, what to capture, what to avoid. Be specific.

Avoid vague instructions like “be helpful and professional”. Instead: “Confirm the caller’s name and date of birth, then ask what they need help with. Do not give medical advice — refer to a clinician.”

Outcomes

Each conversation node has one or more outcomes — the named paths leading out. The Stage Evaluator (a fast LLM running alongside the conversation) decides which outcome fired based on what was said this turn. For each outcome, set:

Label — what shows on the canvas edge.
Condition — natural-language description of when this outcome should fire (e.g. “Caller agreed to book an appointment”). The Evaluator uses this to decide.

A node with no outcomes is a dead end. The runtime requires at least one outgoing edge per non-terminal node.

Entry prompt

Open the Properties Panel and find Advanced → Entry prompt. Text injected into the agent’s prompt the first turn after the call enters this stage. Use it for context the agent needs only on entry — for example:

“The caller has just confirmed they’re an existing patient. Now collect their reason for calling.”

The runtime adds this as [Stage Entry]: ... to the conversation prompt only on the first turn of the stage.

Exit prompt

Advanced → Exit prompt. Text the agent reads on the last turn of the stage as a “before you leave, make sure to…” reminder. The runtime injects it as [IMPORTANT — Correct on this turn] on the next turn.

“Make sure the caller has confirmed the appointment date before ending.”

Max turns

Advanced → Max turns. Hard safety cap on how many user turns the stage can run. When reached, the runtime auto-advances to the first outcome’s target.

Stage type	Recommended max turns
Greeting	2-3
Confirmation / closing	2-3
Triage / data capture	4-6
Complex troubleshooting	6-8

Always set this. Without a cap, a misbehaving stage can spin indefinitely.

Extraction fields

Advanced → Extraction fields. A list of snake_case field names you want the agent to capture as the conversation flows — for example caller_name, phone_number, appointment_time. The runtime injects this as [Capture if mentioned]: ... into the agent’s prompt and tells the Stage Evaluator to look for these fields specifically. Captured values land in the call’s extracted_fields and are saved to the post-call record.

Extraction fields are opportunistic — the agent listens for them but won’t interrogate the caller. Use Output schema below if a field is required before the stage can complete.

Output schema

Security → Output schema. A list of fields that MUST be captured before the stage is allowed to advance. The Stage Evaluator refuses to mark the stage completed until every name in the list is present.

Example: a “Book appointment” stage with output_schema: ["appointment_time", "caller_name", "phone_number"] will not transition out until all three are captured.

This is the right field to use when downstream stages or tools depend on those values being present.

Security gates

Security → Security gates. Prerequisite gates (e.g. ["identity_verified"]) that must already be in extracted_fields before the runtime allows entry to this stage. If a gate is missing, the transition is blocked and the call stays in the previous stage. Use this with Output schema on an upstream stage to enforce flow:

Verification stage

Set output_schema: ["identity_verified"] so the stage cannot complete until verification succeeds.

Sensitive stage

Set security_gates: ["identity_verified"]. The runtime will not enter this stage unless verification has been captured upstream.

Tools

Stage tools let the agent take actions during the call — book a slot, look up a knowledge base, send an SMS, transfer to a human. Drag a tool from the Node Sidebar onto a stage. For each attached tool, you can set:

Tool prompt — natural-language guidance for when the agent should use this tool. Written like “Use when the caller has agreed on a time and confirmed their name and phone number.” The runtime appends this to the stage system prompt as a ## Tool Guidance section.
Configuration — tool-specific options (calendar id, knowledge-base ids, SMS body template, etc.)

Built-in tools

Tool ID	What it does	Common use
`appointment`	Books a slot in a connected calendar	Reception, sales follow-up
`knowledge_lookup`	Searches an internal knowledge base	FAQ-heavy flows
`web_search`	Searches the open web	Public-data lookups (rare)
`send_message`	Sends an SMS or WhatsApp	Booking confirmations, links
`send_email`	Sends an email	Receipts, summaries
`transfer_call`	Hands off to a human or another VoiceFlow	Safeguarding, escalations
`send_dtmf`	Sends a touch-tone digit	Navigating an upstream IVR after transfer

Place a tool on a specific stage when it’s only relevant there (e.g. appointment on the booking stage). Place it on the Global node when it should be available from any stage (e.g. transfer_call so the caller can ask for a human at any time).

Transfer destinations

For transfer_call terminal nodes, set the Transfer target in the Properties Panel:

Human — a labelled queue or specific phone number. The runtime hands the live call off when this terminal is reached.
Workflow — another VoiceFlow. AI-to-AI handoff, useful for escalating from a frontline triage flow to a specialist flow.

Global node — identity and rail guards

The Global node sits at the top of the canvas. Click it to set:

Identity

The agent’s persona — name, role, tone, expertise. This applies to every stage. Be specific.

“You are Sarah, the appointment coordinator at Acme Dental in Boston. You speak warmly and unhurriedly. You know dental insurance terminology but you do not give clinical advice.”

Rail guards

Always-active safety boundaries. Each rail guard has:

Label — short name (e.g. “No medical advice”).
Instructions — what the agent must never do (e.g. “Never diagnose, suggest treatments, or interpret symptoms. Refer all clinical questions to a clinician.”).
Action — what to do when the guard fires:
- block — refuse and redirect.
- warn — flag the violation in analytics but continue.
- escalate — immediately transfer to a human queue.

Rail guards are injected into every turn’s prompt as a ## Rail Guards section — they apply globally regardless of stage.

For regulated industries (medical, legal, financial), always include at least one block rail guard. The AI generator includes a sensible baseline; review it before going live.

Common recipes

Stage 1 — Triage
  output_schema: ["consent_to_share"]
  extraction_fields: ["caller_name", "phone_number"]

Stage 2 — Book
  security_gates: ["consent_to_share"]
  output_schema: ["appointment_time"]
  tools: [appointment]

The “Book” stage cannot be entered until consent is captured upstream.

Safety-first medical triage

Global:
  rail_guards:
    - "No medical advice" → block
    - "Safeguarding override" → escalate

Greeting → Triage (max_turns: 4) → Routing → 4 paths
  Path D = transfer_call to MASH duty line

FAQ agent

Greeting → Q&A:
  tools: [{
    toolId: "knowledge_lookup",
    toolPrompt: "Use for any factual question about our services",
    config: { knowledgeBaseIds: [...] }
  }]
  exit_prompt: "Confirm the caller's question is answered before ending."
  max_turns: 8

Q&A → end_call

Validating your flow

Click Validate in the studio toolbar to get:

A plain-English summary of every stage, tool, and rail guard.
A 0-100 health score across coverage, clarity, safety, completeness, and UX.
Specific suggestions for improvement, with severity (critical / warning / info).
4-6 test scripts — sample call transcripts you can run mentally or via Test Call.

Validation results are cached per-flow — re-clicking on an unchanged flow is instant. Click Regenerate to force a fresh review after edits.

What’s coming next

A few advanced fields are saved by the studio but not yet consumed by the live-call runtime:

Per-tool runtime config for knowledge_lookup and web_search (the tool’s config block — knowledge-base IDs, restricted domains). Today these need to be configured at the campaign level via Settings → Tools, not per-stage.
Stage-level rail guards — only the Global node’s rail guards take effect. Put safety boundaries there.

Configure the rest at the right level for now; per-stage tool config will follow in a coming release.

Documentation Index

​How a stage runs

​Stage instructions

​Outcomes

​Entry prompt

​Exit prompt

​Max turns

​Extraction fields

​Output schema

​Security gates

​Tools

​Built-in tools

​Transfer destinations

​Global node — identity and rail guards

​Identity

​Rail guards

​Common recipes

​Booking flow with consent gate

​Safety-first medical triage

​FAQ agent

​Validating your flow

​What’s coming next

How a stage runs

Stage instructions

Outcomes

Entry prompt

Exit prompt

Max turns

Extraction fields

Output schema

Security gates

Tools

Built-in tools

Transfer destinations

Global node — identity and rail guards

Identity

Rail guards

Common recipes

Booking flow with consent gate

Safety-first medical triage

FAQ agent

Validating your flow

What’s coming next