Skip to main content
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.

​
Configuring the Conversational Flow Layer

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: Advanced turn detection model - faster, more accurate, and more natural than sparrow-0 (recommended)
    • sparrow-0: Legacy turn detection model (available for backward compatibility)
    • time-based: Simple timeout-based turn detection
  • 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 compared to the legacy Sparrow-0.

​
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

​
Relationship with STT Layer

The Conversational Flow layer is the recommended approach for configuring turn-taking behavior with Sparrow-1. This supersedes the legacy Sparrow-0 configuration available in the STT layer via smart_turn_detection.
Legacy Approach: Configuring turn-taking via the STT layer’s smart_turn_detection parameter is a legacy approach that uses Sparrow-0. For new implementations, use the Conversational Flow layer with Sparrow-1 instead.
When you configure the Conversational Flow layer with turn_detection_model set to sparrow-1, these settings override any corresponding settings in the STT layer.

​
Parameter Mapping: Sparrow-0 to Sparrow-1

Here’s how Sparrow-0 (STT layer) parameters map to Sparrow-1 (Conversational Flow layer):
Sparrow-0 (STT Layer)Sparrow-1 (Conversational Flow Layer)Notes
participant_pause_sensitivityturn_taking_patienceControls how long to wait before responding
participant_interrupt_sensitivityreplica_interruptibilityControls how easily the replica can be interrupted
Important: When using Sparrow-1 via the Conversational Flow layer, any conflicting settings in the STT layer (Sparrow-0) will be overridden. For example, if you set participant_pause_sensitivity: "high" in the STT layer but turn_taking_patience: "low" in the Conversational Flow layer with turn_detection_model: "sparrow-1", the Conversational Flow setting (low) will take precedence.

​
Migration Guide

If you’re currently using Sparrow-0 settings in the STT layer and want to upgrade to Sparrow-1: Before (Sparrow-0): 
{
  "layers": {
    "stt": {
      "participant_pause_sensitivity": "high",
      "participant_interrupt_sensitivity": "low"
    }
  }
}
After (Sparrow-1): 
{
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "low",
      "replica_interruptibility": "high"
    }
  }
}
Note the inverted mapping:
  • participant_pause_sensitivity: "high" (quick response) → turn_taking_patience: "low" (eager)
  • participant_interrupt_sensitivity: "low" (hard to interrupt) → replica_interruptibility: "high" (easy to interrupt)
The naming has been updated in Sparrow-1 to be more intuitive from the replica’s perspective.

​
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

​
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": "rfe12d8b9597",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "low",
      "replica_interruptibility": "medium"
    }
  }
}

​
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": "rfe12d8b9597",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "high",
      "replica_interruptibility": "verylow"
    }
  }
}

​
Example 3: Educational Instructor

Delivers complete information with minimal interruption: 
{
  "persona_name": "Instructor",
  "system_prompt": "You are an experienced educator teaching complex topics...",
  "pipeline_mode": "full",
  "default_replica_id": "rfe12d8b9597",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "medium",
      "replica_interruptibility": "low"
    }
  }
}

​
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": "rfe12d8b9597",
  "layers": {
    "conversational_flow": {
      "turn_taking_patience": "low"
    }
  }
}
In this example, the system will automatically set:
  • turn_detection_model: sparrow-1
  • replica_interruptibility: medium

​
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.