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

# Voice configuration

> Voice configuration controls speech recognition, spoken replies and phone-session behavior for an Environment.

## Overview

Voice configuration controls speech recognition, spoken replies and phone-session behavior for an Environment. Agent instructions, Playbooks and tools still define what the agent does.

### Examples of when to use Voice configuration

- **Reduce early interruptions:** tune turn-taking for customers who pause while reading order numbers.
- **Serve different languages:** choose a voice for each conversation `locale`.
- **Collect an account number:** enable phone keypad input and define how the caller submits digits.
- **Bound phone sessions:** set silence and maximum-duration limits.

### Choose how to configure Voice

- [**In Studio**](/docs/guides/studio/voice/configure-voice) — configure the controls and verify a phone call.
- [**Through the API**](/docs/guides/developers/voice/configure-voice) — update the same Environment settings from your backend.

<a id="speech-recognition"></a>

## Speech recognition

Choose how customer speech becomes text.

Speech recognition uses the selected Environment’s speech-to-text provider and language. In **Behaviour → Voice input**, choose the provider before its model and language; available controls belong to that provider.

Choose the speech-recognition provider and its input controls in Behaviour. — Choose the speech-recognition provider and its input controls in Behaviour.

For a custom audio client, the [input format](/docs/api-reference/agent-runtime/voice/audio-input) is negotiated separately from speech-recognition settings. Changing the provider does not convert client microphone frames.

Use the [Studio configuration guide](/docs/guides/studio/voice/configure-voice) or [API configuration guide](/docs/guides/developers/voice/configure-voice).

<a id="turn-taking"></a>

## Turn-taking and interruptions

Balance complete customer turns with timely replies.

Endpointing determines when the agent treats speech as a finished turn. Interruption controls determine when customer speech can interrupt a reply. These solve different problems.

- **Replies start too early:** review the selected recognizer’s end-of-turn or silence controls.
- **Replies wait too long:** test a shorter wait with pauses, dates and account numbers.
- **Agent audio continues after interruption:** in a custom client, stop and clear playback on [`asr.barge-in`](/docs/api-reference/agent-runtime/voice/playback#acknowledge-playback-and-handle-interruptions). `asr.interrupt` alone only reports speech detection.

Provider-specific settings are in the [Voice settings reference](/docs/api-reference/environment/voice-settings). Verify changes over the actual phone or browser connection.

<a id="speech-output"></a>

## Speech output

Choose the voice customers hear and how responses play.

**Behaviour → Voice output** selects the default voice. Its provider determines the available voice and model controls.

Choose the default voice and output behavior in Behaviour. — Choose the default voice and output behavior in Behaviour.

- **Sync audio and text output** keeps text aligned with speech; enabling it can add latency.
- **Pronunciation dictionary** controls how selected terms are spoken.
- **Background audio** and **Audio cue** add the configured background or waiting sound.

A custom client still owns [decoding, playback order and playback acknowledgements](/docs/api-reference/agent-runtime/voice/playback).

<a id="languages"></a>

## Language overrides

Use a different voice for each conversation language.

A language override replaces the default voice when the conversation’s `locale` matches that override. Select the voice for each configured language in **Voice output → Language overrides**.

Phone and widget sessions initialize `locale`. API integrations must set it for their session. This selects a voice; it does not translate the agent’s instructions or select the recognizer’s input language.

Follow [Set voices by language](/docs/guides/building-agents/set-voices-by-language) for Studio setup or [configure `localeOverrides`](/docs/api-reference/environment/voice-settings#voice-setting-fields) through the API.

<a id="keypad-input"></a>

## Keypad input

Collect phone digits with an explicit completion rule.

In phone projects, **Voice input → Keypad input** configures digit collection. Choose a completion key (`#` or `*`), an inter-digit timeout, or both. When no timeout is configured, retain a completion key so the caller can submit.

Keypad collection is active while the agent or input step listens. Where the step exposes **Listen for other triggers**, leave it on; turning it off disables collection there. The current runtime submits at 20 digits even if the delimiter or timeout has not fired. The Environment setting alone does not create a question or store a result. A [custom telephony client](/docs/api-reference/agent-runtime/voice/playback#trace-payloads) must implement the `dtmf` instruction itself.

Use the [configuration walkthrough](/docs/guides/studio/voice/configure-voice#configure-call-controls) to configure and test collection on a phone call.

<a id="call-limits"></a>

## Silence and call duration

End unattended or overlong phone conversations deliberately.

**Session & timeout** contains the phone silence timeout, maximum conversation duration and optional **End message**. The duration limit applies to the whole call; a silence timeout addresses a call waiting without input.

Review silence and maximum-duration settings in Session & timeout. — Review silence and maximum-duration settings in Session & timeout.

Set an End message when callers need an explanation before the maximum duration ends the call. Studio’s Inactivity timeout uses `session.idleTimeout.timeoutMs`. The runtime prefers an enabled positive session timeout; `voice.silenceTimeoutMs` is a fallback. `voice.maxDuration.seconds` controls the whole-call duration. Test each condition independently.

<a id="caller-memory"></a>

## Returning callers

Choose whether variables carry over between calls.

**Remember callers across calls** controls runtime identity for phone sessions. When enabled, the caller’s variables can carry into a subsequent call. When disabled, each call receives a new runtime identity.

The [`callerIdentity`](/docs/api-reference/environment/voice-settings#voice-setting-fields) API value is `phone-number` or `call`. This is separate from the caller’s presented phone number; neither authenticates the customer. Verify account access through your own identity checks before using private customer data.
