Skip to main content
Realtime STT (Auto) detects user turns for you, so your voice agent doesn’t need its own voice activity detector (VAD). Traditional VAD solutions decide whether someone is speaking from audio energy alone. Our model detects turns semantically: it considers the conversational context and whether the user’s sentence is linguistically complete. It can tell whether the user is hesitating, thinking mid-sentence, or genuinely done speaking.

Turn lifecycle

Between user turns, the session is idle. When the user begins speaking, turn.start fires, followed by turn.update events as the transcript builds.

Example: one turn

The user says “Hi I need to cancel my subscription please.”
The first turn.eager_end fires early, after “cancel,” but the user keeps talking, so turn.resume follows. The second turn.eager_end comes when the user really is done, and turn.end confirms it.

Events

The API emits these events to describe the state of the conversation: Only ink-preview returns words and languages. ink-2 events carry transcript only. See Word timestamps and Languages. The lifecycle comes with a few guarantees:
  • The first event in every turn is turn.start.
  • turn.eager_end is always followed by turn.end or turn.resume.
  • turn.resume only fires after a preceding turn.eager_end.
  • turn.end always closes the turn; the next turn starts with a new turn.start.
Discard turns with an empty transcript. turn.end can arrive with transcript: "", for example after a short sound with no words in it. Don’t reply to it, and ignore its languages too. Check turn.eager_end the same way, so you don’t start a reply you’ll throw away. The example code shows where the check goes. If false turns interrupt your agent often, raise the start threshold.

Transcript behavior

The transcript property is cumulative within a turn: it contains the full text transcribed so far in this user turn, not a delta. You do not need to concatenate partial results across events. All emitted text is final: the model never revises text it has already sent. You can use the partial transcript from a turn.update the moment it arrives without worrying about it changing. On ink-preview, words works the same way, with one difference: a word is added only once the model has heard all of it. So during a turn, words can trail transcript slightly. See Word timestamps.

Configuring turn detection

Turn detection is driven by a single signal: at every moment, the model estimates the likelihood that the user is in an active turn, as a value from 0 to 1. Three thresholds on that value decide when to fire turn.start, turn.eager_end, and turn.end. Turn detection ships with defaults that work well for most voice agents. ink-2 and ink-preview share these defaults. Tune them to optimize your agent’s conversational flow for your use case, balancing latency against how accurately the model detects where each turn starts and ends. Each parameter trades latency against accuracy. The table below shows what moving it in either direction does. The three thresholds must stay in order: start_threshold > eager_end_threshold > end_threshold. In addition to the ranges above, each value is constrained by its neighbors to preserve this ordering, so you cannot set an eager end threshold above the start threshold or an end threshold above the eager end threshold. Set them when you connect with query parameters (turn_start_threshold, turn_eager_end_threshold, turn_end_threshold, turn_end_timeout_ms), or change them mid-stream with a config message:

Common configurations

Below are some example configurations that make useful starting points. Pick the one closest to your use case, then tune individual thresholds from there.
  • Balanced is the default, and a good place to start for many voice agent conversations.
  • Responsive favors low latency, for fast back-and-forth conversations.
  • Patient favors accuracy, for callers who pause to think or look up information, or when cutting someone off mid-turn is costly.

Example code

Handle turn.start and turn.end for a working agent: interrupt your agent’s speech when the user starts speaking, and generate a reply when they finish. To cut latency, also handle turn.eager_end. Start generating a reply the moment it fires, then cancel it if turn.resume arrives, or play it the instant turn.end confirms the user is done.

Edge cases

No audio vs silence

The API expects a continuous stream of audio, so send silence (all zeros) while your audio input is muted. If you stop sending audio, the server waits for more audio chunks to arrive rather than assuming the user is silent. This is normally what you want, because it handles network lag.

Draining events

When you’re done sending audio for a session, send {"type": "close"}. The model then flushes any buffered audio and sends the remaining events. Once the model is done, the server closes the socket for you. The server buffers some audio to improve transcription accuracy. If you don’t send the close command, or you stop reading messages early, that buffered audio isn’t processed. That’s fine if you don’t care about the last second of audio.

Joining transcripts

For the final transcript, take the transcript field from each turn.end event, one per completed turn. Add a space between turns when you assemble the full transcript. Turn transcripts don’t include separator spaces, so joining them directly runs words together.
Within a turn, transcript is cumulative. Each turn.update, turn.eager_end, and turn.end event already holds the full text of the turn so far. So if you join the transcripts from turn.update and turn.eager_end events, you repeat parts of the transcript. This is a common source of duplicated text. Treat these events as updates to the turn state, not transcript chunks. Read only turn.end for the final transcript.

Where to go next

Try it out online

See turn detection in action with no sign-up or code required

Use the API

Start building with our Realtime STT API

Use the SDK

Take a look at some real code