> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Control conversation flow, turn-taking, and timeouts

> Configure turn-taking, interruption handling, silence timeouts, and maximum duration to shape the rhythm of your voice agent's conversations.

Conversation flow settings determine the rhythm of a voice conversation. They control when the agent starts speaking, whether users can interrupt mid-speech, and how long the agent waits before acting on silence. Getting these settings right makes conversations feel natural rather than mechanical.

## Turn-taking

Turn-taking defines when the agent yields to the user and when it expects the user to yield back. The platform uses a proprietary model to detect end-of-turn signals from audio rather than relying purely on silence duration, which means it handles natural pauses within a sentence without cutting the speaker off prematurely.

You can tune turn-taking behavior with the following settings:

| Setting                | Description                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Mode**               | `auto` lets the platform manage turns. `manual` requires explicit signals from your code to hand off the turn. |
| **User turn timeout**  | How long the platform waits after the user stops speaking before marking their turn as complete.               |
| **Agent turn timeout** | How long the platform waits for the agent to respond before marking the turn as failed.                        |

<Tip>
  Use `auto` mode for most voice agents. `manual` mode is useful for specialized applications where you need precise control — for example, a dictation app where long pauses are intentional.
</Tip>

## Interruptions

By default, users can interrupt the agent at any time by speaking. When an interruption is detected, the agent stops mid-sentence and starts processing the user's input.

| Option       | Behavior                                                             |
| ------------ | -------------------------------------------------------------------- |
| **Enabled**  | User speech during agent synthesis interrupts the agent immediately. |
| **Disabled** | The agent finishes speaking before the user input is processed.      |

Disable interruptions for scenarios where cutting off the agent causes problems — for example, when the agent is reading legal disclaimers or completing a scripted step that must not be interrupted.

<Note>
  Even with interruptions enabled, very short noises (coughs, background sounds) do not trigger interruptions. The turn-taking model filters out non-speech signals.
</Note>

## Timeout settings

Timeouts control what happens when silence persists during different phases of the conversation.

### User silence timeout

If the user does not speak within a defined window after the agent's turn ends, the agent can respond with a prompt (e.g., "Are you still there?") or end the call.

Configure the timeout duration and the agent's behavior in the **Conversation flow** section of the dashboard or via API:

<CodeGroup>
  ```python python theme={null}
  from xuna_ai import XunaAI

  client = XunaAI()

  agent = client.conversational_ai.agents.update(
      agent_id="your-agent-id",
      conversation_config={
          "conversation": {
              "silence_end_call_timeout": 30,      # seconds before hanging up
              "silence_nudge_timeout": 10,         # seconds before prompting the user
          }
      }
  )
  ```

  ```typescript typescript theme={null}
  import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

  const client = new XunaAIClient();

  await client.conversationalAi.agents.update("your-agent-id", {
    conversationConfig: {
      conversation: {
        silenceEndCallTimeout: 30,  // seconds before hanging up
        silenceNudgeTimeout: 10,    // seconds before prompting the user
      },
    },
  });
  ```
</CodeGroup>

### Maximum conversation duration

Set a hard cap on conversation length to prevent runaway sessions. When the limit is reached, the agent wraps up gracefully.

<CodeGroup>
  ```python python theme={null}
  agent = client.conversational_ai.agents.update(
      agent_id="your-agent-id",
      conversation_config={
          "conversation": {
              "max_duration_seconds": 600,  # 10 minutes
          }
      }
  )
  ```

  ```typescript typescript theme={null}
  await client.conversationalAi.agents.update("your-agent-id", {
    conversationConfig: {
      conversation: {
        maxDurationSeconds: 600, // 10 minutes
      },
    },
  });
  ```
</CodeGroup>

## Configuring conversation flow in the dashboard

<Steps>
  <Step title="Open your agent">
    Go to the [XUNA AI dashboard](https://xuna.ai/app/conversational-ai) and select your agent.
  </Step>

  <Step title="Open the Advanced tab">
    Click the **Advanced** tab in the agent settings panel.
  </Step>

  <Step title="Adjust conversation flow settings">
    Set your preferred values for turn-taking mode, interruption handling, silence timeouts, and max duration.
  </Step>

  <Step title="Save and test">
    Click **Save** and start a test conversation to verify the settings feel natural.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Recommended settings for customer support">
    * **Interruptions**: Enabled
    * **User silence nudge timeout**: 8–10 seconds
    * **User silence end-call timeout**: 25–30 seconds
    * **Max duration**: 600–900 seconds (10–15 minutes)
  </Accordion>

  <Accordion title="Recommended settings for outbound calling">
    * **Interruptions**: Enabled
    * **User silence nudge timeout**: 5–7 seconds
    * **User silence end-call timeout**: 15–20 seconds
    * **Max duration**: 300 seconds (5 minutes)
  </Accordion>

  <Accordion title="Recommended settings for voice UI in apps">
    * **Interruptions**: Enabled
    * **User silence nudge timeout**: Disabled (user controls the session)
    * **Max duration**: No limit, or match your app's session timeout
  </Accordion>
</AccordionGroup>