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

# Conversational Flow

> Learn how to configure the Conversational Flow layer to fine-tune turn-taking and interruption handling behavior.

The **Conversational Flow Layer** in Tavus gives you precise control over the natural dynamics of conversation. This layer allows you to customize how your PAL 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 PAL decides when to speak and when to listen
* **Interruptibility**: How easily the PAL can be interrupted by the user

<Note>
  All conversational flow parameters are optional. When the layer is omitted or any parameter is set, unspecified fields use the defaults below.
</Note>

<Note>
  The PAL's greeting is always non-interruptible, regardless of `pal_interruptibility`. These settings only take effect after the greeting completes.
</Note>

## Configuring the Conversational Flow Layer

<Note>
  If you're migrating from sparrow-0 (formerly called `smart_turn_detection` on the STT Layer) then check out the [migration guide here](/sections/troubleshooting#conversational-flow-vs-stt-relationship-and-migration).
</Note>

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`

```json theme={null}
"turn_detection_model": "sparrow-1"
```

<Tip>
  **Sparrow-1 is recommended for all use cases** as it provides superior performance with faster response times, higher accuracy, and more natural conversational flow.
</Tip>

### 2. `turn_taking_patience`

Controls how eagerly the PAL 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.

```json theme={null}
"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. `pal_interruptibility`

Controls how sensitive the PAL is to user speech while the PAL is talking. Determines whether the PAL stops to listen or keeps speaking when interrupted.

<Note>
  **`replica_interruptibility`** is a legacy alias for this field. Existing requests keep working; use **`pal_interruptibility`** in new integrations.
</Note>

* **Options**:
  * `low`: Less interruptible. The PAL 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.

```json theme={null}
"pal_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.

```json theme={null}
"voice_isolation": "near"
```

### 5. `wake_phrase`

A specific phrase the PAL listens for before responding. When set, the PAL remains silent until it hears the wake phrase, similar to how voice assistants like Siri or Alexa work.

* **Type**: `string`
* **Default**: `None` (disabled)

```json theme={null}
"wake_phrase": "Hey Charlie"
```

**How wake phrases work:**

* The PAL stays silent and does not respond until it hears the specified wake phrase.
* The PAL still "hears" everything that is said. All user utterances are recorded in the transcript so the PAL has full context when it does respond.
* Once the wake phrase is detected, the PAL responds using the full conversation history, including anything said before the wake phrase was triggered.

<Tip>
  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 PAL to respond unintentionally. Phrases with two or more distinctive words (for example, `"Hey Charlie"` or `"Okay Assistant"`) work best.
</Tip>

### 6. `sleep_phrase`

A specific phrase that puts the PAL back to sleep after it has been woken with the `wake_phrase`. When the PAL hears the sleep phrase, it stops responding and returns to the silent state, listening again for the `wake_phrase` before it will respond.

* **Type**: `string`
* **Default**: `None` (disabled)

```json theme={null}
"sleep_phrase": "Thanks Charlie"
```

**How sleep phrases work:**

* After being woken with the `wake_phrase`, the PAL keeps responding normally until it hears the `sleep_phrase`.
* Once the sleep phrase is detected, the PAL goes to sleep: it stops responding and waits for the `wake_phrase` again.
* While asleep, the PAL still "hears" everything that is said. All user utterances are recorded in the transcript so it has full context when it is woken again.

**Example interaction** with `wake_phrase` set to `"Hey Charlie"` and `sleep_phrase` set to `"Thanks Charlie"`:

```text theme={null}
You: "Hey Charlie, what's the weather like today?"
PAL: "Today's forecast is..."
You: "Great, and what about tomorrow?"
PAL: "Tomorrow will be..."
You: "Thanks Charlie, that's all"
PAL: [goes to sleep]
You: "Now let's talk about something else..."
PAL: [no reply]
```

<Tip>
  As with the `wake_phrase`, choose a sleep phrase that is unique enough to avoid over-triggering. Phrases with two or more distinctive words work best.
</Tip>

### 7. `idle_engagement`

Controls whether the PAL proactively re-engages the user after a stretch of silence, and how eagerly.

* **Options**:
  * `off` **(default)**: The PAL never breaks silence - it only speaks in response to user input.
  * `patient`: The PAL re-engages after longer silences. Suited to tutors, coaches, or contemplative use cases where users may need time to think.
  * `eager`: The PAL re-engages after shorter silences. Suited to SDR or sales-style conversations where keeping momentum matters.

```json theme={null}
"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

<Note>
  `idle_engagement` is independent of `turn_taking_patience`. Turn-taking patience controls how quickly the PAL responds after the user finishes speaking; `idle_engagement` controls whether the PAL proactively breaks an extended silence.
</Note>

## Default Behavior

When the layer is omitted or any parameter is set, unspecified fields use:

* `turn_detection_model`: `sparrow-1`
* `turn_taking_patience`: `medium`
* `pal_interruptibility`: `medium`
* `voice_isolation`: `near`
* `wake_phrase`: `None`
* `sleep_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 PAL responds after a user finishes speaking. Set it high when the PAL should avoid interrupting, and low when fast responses are preferred. Use `pal_interruptibility` to control how easily the PAL 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:

```json theme={null}
{
  "pal_name": "Support Agent",
  "system_prompt": "You are a helpful customer support agent...",
  "pipeline_mode": "full",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "low",
      "pal_interruptibility": "medium",
      "voice_isolation": "near"
    }
  }
}
```

### Example 2: Medical Consultation

Patient, thoughtful, with engaged listening for sensitive conversations:

```json theme={null}
{
  "pal_name": "Medical Advisor",
  "system_prompt": "You are a compassionate medical professional...",
  "pipeline_mode": "full",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "high",
      "pal_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:

```json theme={null}
{
  "pal_name": "Instructor",
  "system_prompt": "You are an experienced educator teaching complex topics...",
  "pipeline_mode": "full",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "medium",
      "pal_interruptibility": "low",
      "voice_isolation": "near",
      "idle_engagement": "patient"
    }
  }
}
```

### Example 4: Minimal Configuration

Configure just one parameter - others will use defaults:

```json theme={null}
{
  "pal_name": "Quick Chat",
  "system_prompt": "You are a friendly conversational AI...",
  "pipeline_mode": "full",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "conversational_flow": {
      "turn_taking_patience": "low"
    }
  }
}
```

In this example, the system will automatically set:

* `turn_detection_model`: `sparrow-1`
* `pal_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.

<Note>
  Refer to the <a href="/api-reference/pals/create-pal" target="_blank">Create PAL API</a> for the complete API specification and additional PAL configuration options.
</Note>