Speech Settings: Hierarchy, Inheritance and Value Types

The same speech setting can be defined in four places, and the platform resolves them in a fixed order. Most reports of a setting "not taking effect" come down to one of two causes: the value was set at a level that something more specific overrides, or it was changed after the session or interaction that needed it had already been created. This article explains the layers, the inheritance rules, and the value types, so you can decide where a setting belongs and predict what a given interaction will actually use.

Scope. This article covers the gRPC settings model shared by the speech products: ASR, transcription, TTS, and CPA/AMD. Voice Biometrics is configured differently, through enrollment, verification, and engine configurations identified by configuration symbols. MRCP clients use MRCP headers and client_property.conf, which have their own names and scales (see MRCP clients).

The four layers

For any given setting, the most specific level that defines it wins. A level that does not define the setting passes the decision up to the level above.

Level	Where it is set	What it affects	When a change takes effect
1. Cluster (environment variables)	Helm chart values (`values.yaml`) during installation or upgrade	The whole installation: supported ASR and TTS languages, GPU use, image tags, per-deployment connection strings	On the next `helm` install or upgrade. Cannot be changed while the application is running.
2. Deployment (global)	The Deployment Portal Configuration page, the Management API, or the gRPC `GlobalRequest`	Every session and interaction in one deployment (tenant)	For sessions and interactions created after the change. Running work is not interrupted.
3. Session	`session_set_settings` on the session	Every interaction created in that session	For interactions created after the call
4. Interaction	The interaction create request (for example `InteractionCreateAsrRequest`)	That one interaction	Immediately, because the settings travel with the request

In this context, a deployment is an individual tenant or subscriber within the platform.

Cluster values are installation facts, not defaults

Levels 2 to 4 form a true override chain: each is a default that a more specific level can replace. Cluster values are different. They describe what the installation is able to do, such as which languages are deployed and which databases a deployment connects to, so no session or interaction can override them, and some settings exist only at this level. Treat changes here as a cluster administration task. See Helm Chart Changes in Version 8.0.0 for the speech-related Helm keys.

How inheritance works

Set only what you need to change

Every setting is optional at every level. A setting that is not specified falls back to the value from the level above, and ultimately to the platform default. Set a value explicitly only when you need something other than the default. This keeps overrides easy to audit, and it means a later change to a deployment default reaches every session and interaction that did not override it.

Interactions take a snapshot

When an interaction is created, it takes the settings that apply at that moment from the deployment, session, and its own request. Once it has started, later changes to the deployment or session are not picked up by that interaction. Likewise, changing session settings does not affect interactions that already exist in the session. Every interaction is a child of a session, which is why it inherits that session's settings.

Sessions can carry interaction defaults

Session settings can contain interaction-level groups (for example VAD or recognition settings) that apply to every interaction the session creates. An interaction can then override them in its own create request.

Worked example

Suppose the end-of-speech timeout (vad_settings.end_of_speech_timeout_ms) is set at three levels. The values are for illustration only.

Event	Value used	Why
Deployment default is set to 1000 ms. A session starts and creates interaction A.	1000 ms	Only the deployment level defines it.
The session then sets 1500 ms. Interaction B is created.	1500 ms for B 1000 ms for A	B inherits the session value. A already took its snapshot.
Interaction C is created with 800 ms in its own request.	800 ms	The interaction level is the most specific.
An administrator changes the deployment default to 2000 ms.	No change to A, B, or C	Existing interactions keep their snapshot, and the session override still wins for new interactions in this session.

Reading and changing settings

Deployment Portal

Go to Configuration, then Manage Configurations, then Speech. This is the recommended interface for most operators. See the Portal Help Guide.

Management API

Every setting available in the portal can also be read and written through the Management API, which is useful in air-gapped or headless environments. Configuring Speech Settings Using the Management API walks through the full read, modify, and verify cycle.

gRPC API

Clients that call the speech API directly work with these messages:

session_set_settings and session_get_settings change and read the settings of a session.
The interaction create requests carry the interaction's own settings groups, so interaction-level overrides are supplied when the interaction is created.
global_get_settings_request reads deployment defaults. Its settings_type selects the group to return (session, interaction, grammar, recognition, normalization, VAD, CPA, AMD, audio consume, logging, or phrase list).
reset_settings on the global request resets the deployment's settings to their defaults.

For example, a session-level override of the end-of-speech timeout looks like this (field names as in the API reference; the value is illustrative):

{
  "session_request": {
    "session_set_settings": {
      "interaction_settings": {
        "vad_settings": {
          "end_of_speech_timeout_ms": 1500
        }
      }
    }
  }
}

Avoid the deprecated global fields. On the global request, the individual default fields for interaction, grammar, recognition, normalization, VAD, CPA, AMD, audio consume, phrase list, and TTS settings are marked deprecated in the API reference. Set deployment defaults for those groups through the Deployment Portal or the Management API instead.

Value types

Each setting has a type, and every optional setting is sent as a wrapped value, so the platform can tell "not set" (inherit from the level above) apart from "set to 0" or "set to false". Explicitly setting a value, including false or 0, overrides the inherited one. In JSON, the optional types are written as follows:

Type	JSON representation	Example
Boolean	`true` or `false`	`"use_vad": true`
32-bit integer, float, double	JSON number	`"end_of_speech_timeout_ms": 1500`
64-bit integer	JSON string, so large values are not rounded	`"1234567890123"`
String	JSON string	`"voice": "..."`
Enumeration	The enumeration name as a string	`LOGGING_VERBOSITY_DEBUG`

Ranges, units, and defaults are specific to each setting, and some use -1 to mean "infinite" or "unlimited". Check the range for each setting in the product's settings reference before relying on a value.

Settings groups

Settings are organized into groups. A group can appear at several levels, so the same group can be used to set a deployment default, a session default, or an interaction override.

Group	What it controls	Applies to
`SessionSettings`	Session-wide behavior such as archiving, call and channel identifiers for call detail records, and a container for interaction-level defaults	All products
`InteractionSettings`	Container for the interaction-level groups below	All products
`GeneralInteractionSettings`	Settings common to every interaction type, such as secure context (suppressing sensitive data in logs) and custom interaction data	All interaction types
`AudioConsumeSettings`	How streamed or batch audio is consumed by the interaction	ASR, transcription, CPA, AMD
`VadSettings`	Voice activity detection: whether it is used, barge-in and end-of-speech timing	ASR, CPA, AMD
`GrammarSettings`	Grammar handling, such as the default semantic tag format, load timeouts, and certificate verification for grammar URLs	Grammar-based ASR
`RecognitionSettings`	Recognition behavior, such as confidence threshold, decode timeout, and partial results	ASR
`NormalizationSettings`	Post-processing of transcription output, such as inverse text normalization, capitalization and punctuation, and redaction	Transcription
`NluSettings`	Text analysis such as summarization, translation, topic, and sentiment	NLU
`PhraseListSettings`	Probability boost applied to phrase lists	Transcription
`CpaSettings`	Call progress analysis parameters	CPA
`AmdSettings`	Answering machine and tone detection parameters	AMD
`TtsSettings`	Synthesis behavior, such as mapping alternative voice names to platform voices	TTS
`LoggingSettings`	Logging verbosity	All products

The setting names, types, ranges, and defaults inside each group are listed in the settings reference for each product: the ASR & Transcription Settings Reference, the TTS Settings Reference, and the CPA & AMD Settings Reference.

MRCP clients

The MRCP API server (Media Server) exposes equivalent behavior through MRCP headers and the client_property.conf file, using different setting names, scales, and in some cases different defaults than the gRPC settings. For example, a confidence threshold on a 0 to 1 scale in an MRCP header is not the same number as one on a 0 to 1000 scale in gRPC. Use the MRCP articles for MRCP deployments, and do not mix names or values between the two:

Troubleshooting: a setting is not taking effect

Symptom	Likely cause and fix
A change made in the portal or API has no effect on a call that is already running	Interactions take a snapshot of their settings when they are created. The change applies to sessions and interactions created afterward.
A deployment default is ignored by one application	The application sets the same value at the session or interaction level, which overrides the deployment default. Check what the client sends in its session and interaction requests.
Session settings were applied but the first interaction ignored them	The interaction was created before `session_set_settings` was called. Set session settings before creating the interactions that need them.
A language or connection setting cannot be changed in the portal or API	It is a cluster-level value. Change it in the Helm values and run a Helm upgrade.
The change appears to have no effect for one customer or tenant	Deployment settings apply per deployment. Confirm you edited the deployment whose ID the client sends in `deployment_id`.
A value from an MRCP article does not behave as described for a gRPC client	MRCP and gRPC settings use different names, scales, and defaults. Use the reference that matches the interface the client uses.

Was this article helpful?