ControlsInputs: Client Messages

Update Listen

Update the Listen configuration on the fly — switch the STT model and language, and adjust EOT thresholds and keyterms — without restarting the session.

Voice Agent

The UpdateListen message is a JSON message that updates the speech-to-text configuration during a conversation.

Purpose

The UpdateListen message allows you to change Listen parameters on the fly without restarting the session. You can switch the speech-to-text model and language, and adjust end-of-turn thresholds and keyterms.

The payload uses the same shape as agent.listen in the Settings message — every field lives under listen.provider.

Tunable Parameters

ParameterTypeDescription
listen.provider.modelStringSpeech-to-text model to switch to, such as nova-3-general or flux-general-multi.
listen.provider.languageStringLanguage code for transcription, such as en or multi. Supported with V1 (Nova) models.
listen.provider.versionStringDeepgram speech-to-text API version: v1 for Nova models, v2 for Flux.
listen.provider.eot_thresholdNumberConfidence threshold for end-of-turn detection. Valid range: 0.5 - 0.9.
listen.provider.eager_eot_thresholdNumberConfidence threshold for eager end-of-turn detection. Valid range: 0.3 - 0.9.
listen.provider.eot_timeout_msIntegerTime in milliseconds after speech to finish a turn regardless of EOT confidence.
listen.provider.keytermsArrayKeyterms to boost recognition for. Replaces the current keyterms list. Flux models only.
listen.provider.language_hintsArrayArray of BCP-47 language codes to bias toward. Only supported with flux-general-multi. See supported languages.

Send the fields that apply to the model you are switching to: language for V1 (Nova) models, and keyterms, the end-of-turn fields, and language_hints for V2 (Flux) models.

Keyterms can only be updated mid-session for Flux models. Nova-3 keyterms are fixed for the life of the session — set them in the Settings message at the start of the session, which works for both Flux and Nova-3.

Partial Update Semantics

UpdateListen is a partial update — any tunable field you omit keeps its current value, with one exception:

language_hints is cleared (reset to empty) when omitted. Always re-send language_hints if you want to preserve language biasing.

Example Payloads

To send the UpdateListen message, send the following JSON message to the server:

1{
2    "type": "UpdateListen",
3    "listen": {
4        "provider": {
5            "type": "deepgram",
6            "version": "v1",
7            "model": "nova-3-general",
8            "language": "es"
9        }
10    }
11}

Upon receiving the UpdateListen message, the server applies the changes and returns a ListenUpdated message.

JSON
1{
2    "type": "ListenUpdated"
3}