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.”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_endis always followed byturn.endorturn.resume.turn.resumeonly fires after a precedingturn.eager_end.turn.endalways closes the turn; the next turn starts with a newturn.start.
Transcript behavior
Thetranscript 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 from0 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
Handleturn.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 thetranscript 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.
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