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

# Voice

When an agent is configured with a phone number, it answers calls as a real-time agent. It is implemented with Telnyx-hosted Speech to Text (STT) and Text to Speech (TTS) models, and both are configured in the `voice` block of [`agent.json`](/docs/agents/reference/agent-json#voice). `telnyx-acp set voice.<knob> <value>` changes one knob, and the next `deploy` ships it. Phone calls do not reach `dev`; with `web` set, the page's mic button under `dev` tries the greeting, `bargeIn`, `keypressInterrupts`, `stt` and `tts` locally, while `eager`, `filler` and `harness` show on the deployed agent only.

```json theme={null}
"voice": {
  "eager": true,
  "bargeIn": { "minWords": 2 },
  "stt": { "eotThreshold": 0.7, "eagerEotThreshold": 0.5, "eotTimeoutMs": 1500 },
  "tts": { "voice": "Telnyx.Ultra.00967b2f-88a6-4a31-8153-110a92134b9f" }
}
```

```bash theme={null}
telnyx-acp set voice.stt.eotThreshold 0.8
telnyx-acp set voice.tts.voice Telnyx.KokoroTTS.af_bella
```

## Phone Numbers

```bash theme={null}
telnyx-acp add phone +15550001234
telnyx-acp deploy
```

`deploy` puts the number on a Call Control application and points its webhook at the agent. A number that is missing from the account, or not active yet, stops the `deploy`. `telnyx-acp status` shows whether the webhook still points at the agent. `remove phone` plus the next `deploy`, or `delete`, put the number back where it was. The same number answers texts, which [Messaging](/docs/agents/messaging) covers.

A caller hears ringing while the agent instance is placed, typically one to three seconds. The agent then speaks the greeting. Each thing the caller says is a turn, and by default it goes straight to the model and the reply is spoken sentence by sentence. The caller talking over the agent stops it.

> [!NOTE]
>
> `voice.harness: true` runs the harness per turn instead, with the tools on the call, at the cost of a second or more before the first word; a turn on a call is not a durable run. A tool marked `ask` stays out of calls, since a call cannot wait for an approval.

Inside the Managed Harness follows a call through the code: [Phone](/docs/agent-sdk/inside/configuration/phone) for what `deploy` wires, [The Call Webhook](/docs/agent-sdk/inside/request-handling/call-webhook) for answering, and [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) for each turn.

## STT

`stt` tunes when a caller's turn is over. `validate` holds each value to its range.

| Field | Default | Range | Meaning |
| - | - | - | - |
| `stt.eotThreshold` | the platform's | `0.5` to `0.9` | The STT model's confidence to confirm the end of a turn; higher waits longer. |
| `stt.eagerEotThreshold` | `0.5` | `0.3` to `0.9`, at most `eotThreshold` | The confidence at which an eager turn starts; lower fires earlier and is wrong more often. |
| `stt.eotTimeoutMs` | the platform's | `500` to `10000` | Silence, in milliseconds, after which the turn ends regardless. |

Three settings beside it decide what happens at the boundary:

| Field | Default | Meaning |
| - | - | - |
| `eager` | `true` | The reply starts on the STT model's first guess of the end of the turn; the words are then confirmed or the turn is discarded. Off, the reply waits for the confirmed end. |
| `bargeIn` | `true` | The caller talking over the agent stops it once two words are heard; `true` is `{ "minWords": 2 }`. `{ "minWords": 0 }` stops on any sound, `false` never stops. |
| `keypressInterrupts` | `false` | A keypad press stops the agent. |

## TTS

| Field | Default | Meaning |
| - | - | - |
| `tts.voice` | `Telnyx.Ultra.00967b2f-88a6-4a31-8153-110a92134b9f` | A Telnyx voice, `Telnyx.<model>.<voice>`, for example `Telnyx.KokoroTTS.af_bella`. [List available voices](/api-reference/text-to-speech-commands/list-available-voices) has them all. |
| `tts.voiceSettings` | none | The provider's own settings, passed through unchanged. |

The reply is passed to TTS sentence by sentence as the model writes it, which is why [the instructions](/docs/agents/models-and-instructions#instructions) for a voice agent ask for short spoken sentences.

## Filler

When the model is slow to start, the call says a short phrase so the caller hears that the agent is there. It is on by default. `filler.afterMs`, `700` by default (`100` to `5000`), is how long after the caller is confirmed done the phrase is said; `filler.phrases` are one to ten short sentences said in turn, "One moment.", "Let me check that for you." and "Sure, just a second." by default; `filler.maxPerCall` caps how many turns in one call are filled, `0` for all of them. `telnyx-acp set voice.filler false` turns it off. The phrase is spoken, never written to the message log or to memory, and each one is a `voiceFiller` line in the logs.

## Optimize for Latency

On a call the number that matters is the time from the caller falling silent to the first reply audio. On the default settings it is about one second, measured with hosted Llama 3.3 70B and Telnyx STT and TTS. Every choice below adds to that second or takes from it.

| Stage | What Decides It |
| - | - |
| End of turn | The STT model's confidence that the caller has stopped, and the silence timeout behind it. |
| First token | The model: how fast it starts answering, and whether it thinks before it speaks. |
| First audio | TTS of the first sentence, started as soon as the model has written one. |

Placement is mostly off that path: the instance is woken while the phone is still ringing, for up to four seconds; past that the call is answered anyway and the first turn carries the start-up.

| Choice | Setting | Effect |
| - | - | - |
| A hosted, non-reasoning model | `model` | Fast to its first token. A reasoning model such as `zai-org/GLM-5.2` thinks before its first word, which the caller hears as seconds of silence. |
| The direct engine | `voice.harness: false`, the default | The turn goes straight to the model. The harness per turn adds a second or more before the first word, in exchange for tools on the call (a tool marked `ask` stays out of calls). |
| Eager end of turn | `voice.eager: true`, the default | The reply starts on the STT model's first guess; the words are confirmed or the turn is discarded. Turn it off only if the agent too often answers a sentence the caller had not finished. |
| Short spoken sentences | `instructions.md` | The first sentence goes to TTS as soon as it is written, so the shorter it is, the sooner the caller hears it. |
| A short greeting, as a question | `voice.greeting` | Spoken verbatim the moment the call is answered, while the first read happens; it tells the caller to speak. |
| Real interruptions only | `voice.bargeIn: true`, the default | Two words stop the agent, "mm-hm" does not; `{ "minWords": 4 }` waits for more. |

`stt.eotTimeoutMs` is the longest silence before a turn ends regardless: raise it for callers who pause mid-sentence, lower it for snappier turns. `stt.eagerEotThreshold` and `stt.eotThreshold` are the confidences for the early signal and the confirmed one; [STT](#stt) has the ranges. With memory on, the summary read is bounded at one second, and a slow read means the first turn runs without it rather than waiting.

## Measure

Calls need a phone: call the number. Each call writes one JSON line per event, `voiceWake`, `voiceCall`, `voiceTurn`, `voiceFiller` and `modelStream` among them, and every turn's `voiceTurn` line carries `toFirstAudioMs` and the milliseconds to each stage, so a change can be judged on the next call rather than by ear:

```bash theme={null}
telnyx-acp logs --since 10m | grep voiceTurn
```

[logs](/docs/agents/cli/logs) reads them line by line. The page's voice turns under `dev` print the same `voiceTurn` line in the terminal, on the direct engine without eager starts, so they measure the model and the speech services rather than a deployed call.

## Beta Limitations

* **Speech settings.** STT and TTS run with their default language and model. `voice.stt` tunes end-of-turn detection only, and `voice.tts` picks the voice and passes provider settings through.
* **TeXML applications.** A `texml_application` channel is declared, validated and wired, but its handler is not implemented, and a webhook to it answers 501. Calls go through a phone number or a `call_control_application` channel.