Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tavus.io/llms.txt

Use this file to discover all available pages before exploring further.

The Conversational Flow Layer in Tavus gives you precise control over the natural dynamics of conversation. This layer allows you to customize how your replica handles turn-taking and interruptions to create conversational experiences that match your specific use case.

​
Understanding Conversational Flow

Conversational flow encompasses the subtle dynamics that make conversations feel natural:
  • Turn-taking: How the replica decides when to speak and when to listen
  • Interruptibility: How easily the replica can be interrupted by the user
All conversational flow parameters are optional. When not explicitly configured, the layer remains inactive. However, if you configure any single parameter, the system will apply sensible defaults to all other parameters to ensure consistent behavior.
The replica’s greeting is always non-interruptible, regardless of replica_interruptibility. These settings only take effect after the greeting completes.

​
Configuring the Conversational Flow Layer

If you’re migrating from sparrow-0 (formerly called smart_turn_detection on the STT Layer) then check out the migration guide here.
Define the conversational flow layer under the layers.conversational_flow object. Below are the parameters available:

​
1. turn_detection_model

Specifies the model used for detecting conversational turns.
  • Options:
    • sparrow-1 (default): Advanced turn detection model - faster, more accurate, and more natural (recommended)
    • sparrow-0: Legacy turn detection model (API-only, not actively supported)
    • timebased: Simple time-based turn detection (API-only, not actively supported)
  • Default: sparrow-1 
"turn_detection_model": "sparrow-1"
Sparrow-1 is recommended for all use cases as it provides superior performance with faster response times, higher accuracy, and more natural conversational flow.

​
2. turn_taking_patience

Controls how eagerly the replica claims conversational turns. This affects both response latency and the likelihood of interrupting during natural pauses.
  • Options:
    • low: Eager and quick to respond. May interrupt natural pauses. Best for rapid-fire exchanges or customer service scenarios where speed is prioritized.
    • medium (default): Balanced behavior. Waits for appropriate conversational cues before responding.
    • high: Patient and waits for clear turn completion. Ideal for thoughtful conversations, interviews, or therapeutic contexts.
"turn_taking_patience": "medium"
Use Cases:
  • low: Fast-paced customer support, quick information lookups, casual chat
  • medium: General purpose conversations, sales calls, presentations
  • high: Medical consultations, legal advice, counseling sessions

​
3. replica_interruptibility

Controls how sensitive the replica is to user speech while the replica is talking. Determines whether the replica stops to listen or keeps speaking when interrupted.
  • Options:
    • low: Less interruptible. The replica keeps talking through minor interruptions.
    • medium (default): Balanced sensitivity. Responds to clear interruption attempts.
    • high: Highly sensitive. Stops easily when the user begins speaking, maximizing user control.
"replica_interruptibility": "high"
Use Cases:
  • low: Educational content delivery, storytelling, guided onboarding
  • medium: Standard conversations, interviews, consultations
  • high: User-driven conversations, troubleshooting, interactive support

​
4. voice_isolation

Voice isolation separates speech from background noise in the participant’s microphone audio. It is enabled by default for improved audio quality and can be disabled if needed.
  • Options:
    • near (default): Separates speech from background noise for scenarios where the user is less than 1 meter away from the microphone.
    • off: No voice isolation model is used. The raw audio is sent down the conversational pipeline.
"voice_isolation": "near"

​
5. wake_phrase

A specific phrase the persona listens for before responding. When set, the persona remains silent until it hears the wake phrase, similar to how voice assistants like Siri or Alexa work.
  • Type: string
  • Default: None (disabled)
"wake_phrase": "Hey Siri"
How wake phrases work:
  • The persona stays silent and does not respond until it hears the specified wake phrase.
  • The persona still “hears” everything that is said. All user utterances are recorded in the transcript so the persona has full context when it does respond.
  • Once the wake phrase is detected, the persona responds using the full conversation history, including anything said before the wake phrase was triggered.
Choose a wake phrase that is unique enough to avoid over-triggering. Avoid generic greetings like "Hey" or single common words, which can cause the persona to respond unintentionally. Phrases with two or more distinctive words (for example, "Hey Siri" or "Okay Assistant") work best.

​
6. idle_engagement

Controls whether the replica proactively re-engages the user after a stretch of silence, and how eagerly.
  • Options:
    • off (default): The replica never breaks silence — it only speaks in response to user input.
    • patient: The replica re-engages after longer silences. Suited to tutors, coaches, or contemplative use cases where users may need time to think.
    • eager: The replica re-engages after shorter silences. Suited to SDR or sales-style conversations where keeping momentum matters.
"idle_engagement": "patient"
Use Cases:
  • off: General conversational use cases where the user always drives the next turn
  • patient: Tutoring, coaching, therapy, interviews
  • eager: Outbound sales, SDR, qualification calls
idle_engagement is independent of turn_taking_patience. Turn-taking patience controls how quickly the replica responds after the user finishes speaking; idle_engagement controls whether the replica proactively breaks an extended silence.

​
Default Behavior

When the conversational flow layer is not configured, all parameters default to None and the layer remains inactive. However, if you configure any single parameter, the system automatically applies the following defaults to ensure consistent behavior:
  • turn_detection_model: sparrow-1
  • turn_taking_patience: medium
  • replica_interruptibility: medium
  • voice_isolation: near
  • wake_phrase: None
  • idle_engagement: off

​
Example Configurations

The following example configurations demonstrate how to tune conversational timing and interruption behavior for different use cases. Use turn_taking_patience to bias how quickly the replica responds after a user finishes speaking. Set it high when the replica should avoid interrupting, and low when fast responses are preferred. Use replica_interruptibility to control how easily the replica recalculates its response when interrupted; lower values are recommended for most experiences, with higher values reserved for cases where frequent, abrupt interruptions are desirable. Sparrow-1 dynamically handles turn-taking in all cases, with these settings acting as guiding biases rather than hard rules.

​
Example 1: Customer Support Agent

Fast, responsive, and easily interruptible for customer-driven conversations: 
{
  "persona_name": "Support Agent",
  "system_prompt": "You are a helpful customer support agent...",
  "pipeline_mode": "full",
  "default_replica_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "low",
      "replica_interruptibility": "medium",
      "voice_isolation": "near"
    }
  }
}

​
Example 2: Medical Consultation

Patient, thoughtful, with engaged listening for sensitive conversations: 
{
  "persona_name": "Medical Advisor",
  "system_prompt": "You are a compassionate medical professional...",
  "pipeline_mode": "full",
  "default_replica_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "high",
      "replica_interruptibility": "verylow",
      "voice_isolation": "near"
    }
  }
}

​
Example 3: Educational Instructor

Delivers complete information with minimal interruption, and gently re-engages the user after long pauses for thought: 
{
  "persona_name": "Instructor",
  "system_prompt": "You are an experienced educator teaching complex topics...",
  "pipeline_mode": "full",
  "default_replica_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "medium",
      "replica_interruptibility": "low",
      "voice_isolation": "near",
      "idle_engagement": "patient"
    }
  }
}

​
Example 4: Minimal Configuration

Configure just one parameter—others will use defaults: 
{
  "persona_name": "Quick Chat",
  "system_prompt": "You are a friendly conversational AI...",
  "pipeline_mode": "full",
  "default_replica_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_taking_patience": "low"
    }
  }
}
In this example, the system will automatically set:
  • turn_detection_model: sparrow-1
  • replica_interruptibility: medium
  • voice_isolation: near

​
Best Practices

​
Match Flow to Use Case

Choose conversational flow settings that align with your application’s purpose:
  • Speed-critical applications: Use low turn-taking patience and high interruptibility
  • Thoughtful conversations: Use high turn-taking patience
  • Important information delivery: Use low interruptibility
  • User-controlled interactions: Use high interruptibility

​
Consider Cultural Context

Conversational norms vary across cultures. Some cultures prefer:
  • More overlap and interruption (consider lower commitment, higher interruptibility)
  • Clear turn-taking with pauses (consider higher patience, lower interruptibility)

​
Test with Real Users

Conversational flow preferences can be subjective. Test your configuration with representative users to ensure it feels natural for your audience.
Refer to the Create Persona API for the complete API specification and additional persona configuration options.