Voice

The voice layer turns an Agent into a real-time voice agent: a call looks like one text turn per utterance, and the platform runs speech-to-text, synthesis, pacing, barge-in, and the per-turn clock. See the Build a Voice Agent guide for the end-to-end tutorial.

import { voice } from "@telnyx/edge-runtime/voice";
import { Agent } from "@telnyx/edge-runtime";

export class Support extends voice(Agent<Env>) {
  protected override reply(transcript: string, call: VoiceCall) {
    return this.respond(transcript, call.confirmed, call.signal);
  }
  override webSocket(ws: WebSocket) {
    this.answer(ws);
  }
}

`voice(Base)`

The mixin. Wrap Agent (or an Agent subclass) with voice() to add the turn engine and the hooks below. The class stays a normal Agent — durable state, messages, RPC, and everything else work unchanged.

Hooks

Override these protected methods. Only reply() is required.

`reply(transcript, call)`

Required. One turn. Called the moment the recognizer guesses the caller has stopped — about 300 ms before it is sure. Return an AsyncGenerator<string> (or a string, or undefined to stay silent); the tokens are synthesized and streamed as they arrive.

Do not await call.confirmed at the top of reply(). Start the model on transcript now — that speculative head start is the largest latency win the layer offers. Commit history from call.confirmed inside the work the generator does; if the guess was wrong the turn is withdrawn and leaves no trace.

`greeting(call)`

Spoken as soon as the call is answered, before the caller says anything. Return a string (or undefined for no greeting).

`webSocket(ws)`

The media stream arrives here. Call this.answer(ws, options) to hand it to the voice layer. This override is required — without it the socket opens and the call is never picked up.

`turnEnded(metrics, call)`

Called once per turn with a VoiceTurnMetrics — the per-stage clock. Use it for latency logging.

`bargedIn(call, cut)`

Called when the caller interrupts the agent mid-sentence. cut is a VoiceBargeIn with what the agent was going to say and what the caller is confirmed to have heard.

`keyPressed(digit, call)`

A DTMF digit. Return a reply like reply(), or undefined.

`streamError(error, call)` · `callEnded(call, reason)`

Error and lifecycle hooks. callEnded fires once with the end reason ("closed", "error", …).

`speechProviders()`

Return the STT/TTS pair, e.g. telnyxSpeechProviders({ synthesizer: { voice: "..." } }). The default pair is Telnyx Flux STT + Telnyx TTS over the runtime’s bound connection.

`answer(ws, options?)`

Hands the media socket to the voice layer and returns the VoiceSession. Per-call knobs go in options (AnswerOptions).

this.answer(ws, { bargeIn: { minWords: 2 }, warmup: true });

`AnswerOptions`

Option	Type	Meaning
`eager`	`boolean`	Start the model on the recognizer’s guess, before end-of-turn is confirmed (~300 ms head start). Default `true`.
`warmup`	`boolean`	Open the TTS connection on answer and hold it warm, so no turn pays a cold synthesis handshake. Effective only for voices that accept a streaming connection.
`bargeIn`	`{ minWords?: number }`	Let the caller interrupt the agent. `minWords` ignores backchannels (“uh-huh”) until that many words are heard.
`keypressInterrupts`	`boolean`	Whether a DTMF digit stops playback.
`track`, `preRollMs`, `sentences`, `callControl`, `socket`	—	Lower-level media/session tuning.
`recognizer`, `synthesizer`	`SpeechProvider`	Override the STT/TTS pair for this call (same shape as `speechProviders()`).

`VoiceCall`

The call handle passed to every hook. Read-only fields plus the Call Control verbs.

Member	Type	Meaning
`callControlId`	`string`	The call’s Call Control id — the same id the verbs act through.
`from`, `to`	`string`	The caller and callee numbers.
`channel`	`VoiceChannel`	The transport the turn arrived on.
`history`	`MessageLog`	The agent’s durable conversation log — one conversation across phone and chat. The layer never writes to it; your turn code does.
`confirmed`	`Promise<string \| undefined>`	Resolves to the confirmed transcript, or `undefined` if the turn was withdrawn. Commit history from this.
`signal`	`AbortSignal`	Aborts when the turn is superseded/interrupted/ended — pass it to the model call.
`turn`	`number`	Which turn of the call, from 1.
`speculative`	`boolean`	Whether this call fired on the recognizer’s guess (eager) rather than a confirmed end-of-turn.
`aborted`	`boolean`	`true` once this turn was abandoned. Check it around anything slow.
`hangup()`, `say()`, …	—	Call Control verbs on the live call.

`VoiceTurnMetrics`

The per-turn clock, passed to turnEnded. Headline figure: toFirstAudioMs — caller speech-stop → first assistant audio.

Field	Meaning
`turn`	Turn number (from 1).
`transcript`	What the caller said (confirmed, or the guess if withdrawn).
`started`	How the turn began.
`outcome`	How it ended (`"completed"`, `"barged-in"`, `"withdrawn"`, `"error"`, …).
`toFirstAudioMs`	Speech-stop → first audio (the headline).
`anchor`	Which signal `toFirstAudioMs` is measured from (`"speechStop"` / `"eagerEndOfTurn"` / `"endOfTurn"`).
`at`	Timeline of stage timestamps: `speechStop`, `endOfTurn`, `firstToken`, `synthesisRequested`, `synthesisFirstAudio`, `firstAudio`.
`synthesis`	`{ path, cached, timeToFirstAudioMs }` — how TTS was served (warm vs cold).

`VoiceBargeIn`

Passed to bargedIn.

Field	Meaning
`text`	Everything the interrupted stretch was going to say.
`heard`	The part the caller is confirmed to have heard before the cut (sentences whose playback was confirmed). Empty if the cut landed in the first sentence.

Providers

`telnyxSpeechProviders(options?)`

Returns the { recognizer, synthesizer } pair. Override the voice via synthesizer.voice:

telnyxSpeechProviders({ synthesizer: { voice: "Telnyx.NaturalHD.Alloy" } });

`createCallControlClient()`

A pre-credentialed Call Control client (for the webhook’s answer / streaming_start), using the runtime’s bound connection — no API key in your code.

Also exported

VoiceSession, attachVoiceSocket, sessionOf, TelnyxSpeechRecognizer, TelnyxSpeechSynthesizer, SentenceAssembler, PlayoutQueue, JitterBuffer, and the codec registry — for building a voice loop without the mixin, or replacing a stage. See the source TSDoc in @telnyx/edge-runtime/voice for the full surface.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

`voice(Base)`

Hooks

`reply(transcript, call)`

`greeting(call)`

`webSocket(ws)`

`turnEnded(metrics, call)`

`bargedIn(call, cut)`

`keyPressed(digit, call)`

`streamError(error, call)` · `callEnded(call, reason)`

`speechProviders()`

`answer(ws, options?)`

`AnswerOptions`

`VoiceCall`

`VoiceTurnMetrics`

`VoiceBargeIn`

Providers

`telnyxSpeechProviders(options?)`

`createCallControlClient()`

Also exported

​voice(Base)

​Hooks

​reply(transcript, call)

​greeting(call)

​webSocket(ws)

​turnEnded(metrics, call)

​bargedIn(call, cut)

​keyPressed(digit, call)

​streamError(error, call) · callEnded(call, reason)

​speechProviders()

​answer(ws, options?)

​AnswerOptions

​VoiceCall

​VoiceTurnMetrics

​VoiceBargeIn

​Providers

​telnyxSpeechProviders(options?)

​createCallControlClient()

​Also exported

`voice(Base)`

Hooks

`reply(transcript, call)`

`greeting(call)`

`webSocket(ws)`

`turnEnded(metrics, call)`

`bargedIn(call, cut)`

`keyPressed(digit, call)`

`streamError(error, call)` · `callEnded(call, reason)`

`speechProviders()`

`answer(ws, options?)`

`AnswerOptions`

`VoiceCall`

`VoiceTurnMetrics`

`VoiceBargeIn`

Providers

`telnyxSpeechProviders(options?)`

`createCallControlClient()`

Also exported