> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/workspaces/voice-configuration.md). # Voice Configuration Every voice service has a `voice_config` object that controls how the real-time pipeline behaves during calls. It covers latency tuning, filler behavior, response length limits, barge-in sensitivity, emotion modulation, voice model and TTS provider selection, and tool access. If you leave `voice_config` null, the service has no service-level overrides. Each field is optional, but inheritance depends on the field. `session_provider` resolves service > agent > environment. `tts_provider` resolves service > agent > workspace > environment. Per-language maps check the exact language, base language, and `multilingual` key in that order, with service > agent > workspace precedence within each key. Unset tuning fields use their runtime defaults. ## Field Reference ### Latency These fields control how quickly the agent responds after the caller stops speaking. | Field | Type | Default | Description | | ------------------------ | ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tts_model` | `"sonic-turbo"` or `"sonic-3"` | inherited | Service-level TTS model override. `sonic-turbo` targets \~40ms time-to-first-audio and is best for snappy conversations. `sonic-3` targets \~90ms but produces higher-quality speech with better prosody on longer utterances. Null removes this service-level override; merged workspace, agent, or service provider configuration can still select a model before the environment fallback. | | `max_buffer_delay_ms` | `int` (200-1000) | `500` | How long the pipeline buffers generated text before sending it to TTS. Lower values make the agent start speaking sooner, but may produce choppier speech because each TTS chunk has less context. | | `eager_eot_threshold` | `float` (0.0-1.0) | inherited | End-of-turn confidence threshold. Higher values make the system more aggressive about deciding the caller has finished talking. A value of 0.8 means "start responding when 80% confident the caller is done." Lower values reduce latency but increase the chance of cutting the caller off mid-sentence. | | `eot_timeout_ms` | `int` | inherited | Hard silence timeout in milliseconds. If the caller stops speaking for this long, the system forces an end-of-turn regardless of the confidence score. Useful as a safety net for the confidence-based detection. | | `post_eot_pause_ms` | `int` | `200` | Intentional breath after the caller stops speaking, in milliseconds. | | `transition_deadline_ms` | `int` | `800` | Maximum silence after caller end-of-turn before a filler is injected, in milliseconds. | | `empathy_hold_ms` | `int` | `500` | Intentional silence held for empathy moments, in milliseconds. | ### Fillers Fillers are the short sounds or phrases the agent produces while the LLM generates the full response. They fill what would otherwise be dead air. | Field | Type | Default | Description | | ---------------------- | ------------------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `filler_style` | `"backchannel"`, `"phrase"`, or `"silent"` | `"backchannel"` | Controls the agent's autonomous fillers. Only `silent` changes runtime behavior: it mutes the agent's autonomous backchannels (the navigation acknowledgment and tool-wait acknowledgments). `backchannel` and `phrase` are currently advisory: the per-tool wait style is driven by the context graph's progress hints, not this field. Explicit context graph progress phrases still play even under `silent`. | | `filler_vocabulary` | `list[str]` | null | Custom words for the short acknowledgment played when navigation is skipped (e.g., `["Mm", "Yeah", "Mhm"]`). Does not change tool-execution wait phrases - those come from `progress_vocabulary` or the context graph's progress phrases. | | `backchannel_delay_ms` | `int` (400-1000) | `400` | How many milliseconds the pipeline waits before playing a backchannel when navigation is skipped (the caller said something that doesn't require a state change). Lower values make the agent feel more responsive; higher values feel more deliberate. | | `progress_vocabulary` | `list[str]` | null | Custom phrases for the tool-execution wait filler (distinct from `filler_vocabulary`). Ignored when the active tool's context graph progress hint is deterministic - scripted progress phrases play verbatim in that case. | | `filler_cooldown_ms` | `int` | `2000` | Minimum gap in milliseconds between consecutive fillers. | | `progress_interval_ms` | `int` | `3000` | How often to produce progress audio during tool execution, in milliseconds. | ### Response Hard caps on how much the agent says per turn. These are mechanically enforced by the pipeline (it truncates the output), not just prompted. | Field | Type | Default | Description | | ------------------------ | ----- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `max_response_sentences` | `int` | null (unlimited) | Maximum sentences per response. Set to 1 or 2 for voice services where brevity matters. The pipeline counts sentences by punctuation and cuts off after the limit. | | `max_response_words` | `int` | null (unlimited) | Maximum words per response. Same mechanical enforcement. Useful when you want finer control than sentence-level truncation. | ### Barge-in Barge-in is when the caller starts speaking while the agent is still talking. These fields control how sensitive that detection is. | Field | Type | Default | Description | | ----------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `barge_in_min_speech_s` | `float` | `0.25` | Minimum duration of caller speech (in seconds) before a barge-in triggers. The default of 0.25s lets short phrases ("yes", "no", roughly 200-400ms) interrupt the agent while the recognized-words gate keeps noise out. Duration alone never triggers a barge-in - the pipeline also requires recognized interim words from the STT engine, so breath sounds and background noise do not cause false interrupts. Raising the value (e.g., 1.0+) makes the agent feel like it ignores short interjections. | | `barge_in_cooldown_s` | `float` | `1.5` | Cooldown period after a barge-in before another one can fire. Prevents rapid-fire interruptions where the caller and agent keep cutting each other off. | ### Emotion Modulation | Field | Type | Default | Description | | --------------- | ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `min_tts_speed` | `float` (0.5-1.0) or null | null (no floor) | Minimum TTS speed the empathy engine can set. The empathy system reduces speaking speed after detecting caller distress, but without a floor the reduction can make the agent sound unnaturally slow. Set this to prevent over-modulation while preserving the warmth response. Values are relative to normal speed (e.g., `0.85` means the agent never drops below 85% of normal speed). | ### Voice Model and TTS Provider | Field | Type | Default | Description | | -------------------- | -------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | | `session_provider` | `"amigo"`, `"gpt_realtime"`, or `"gpt_live"` | inherited | Overrides the voice model family at the service level. Null inherits the agent value and then the environment default. | | `tts_provider` | `"cartesia"`, `"elevenlabs"`, or `"groq"` | inherited | Overrides the TTS provider at the service level. Null inherits from agent, workspace, and environment tiers. | | `tts_config` | object | null | Provider-specific configuration bag; keys depend on `tts_provider`. | | `language_providers` | object | null | Per-language TTS provider map (up to 10 entries). Keys are BCP-47 language codes or `multilingual`. | ### Tools | Field | Type | Default | Description | | ---------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `forward_call_enabled` | `bool` | `false` | Whether the `forward_call` tool is available during conversations. This is opt-in because call forwarding has cost and compliance implications. Even when enabled, the context graph's TurnPolicy can further gate forwarding (e.g., `block_forward_call_after_turns`). | | `forwarding` | object or null | null | Per-service call-forwarding destination: `{ "forward_to": "" }`. Used by the `forward_call` tool as the static fallback destination when the agent does not pass an explicit number and no EHR location is configured. | ## Named Presets Agent Forge exposes five named presets. A preset sets multiple fields at once as a starting configuration. | Preset | TTS Model | Buffer Delay | Filler Style | Backchannel Delay | Response Cap | Best For | | ------------------- | ------------- | ------------ | ------------- | ----------------- | ------------ | ----------------------------------------------------------------------------------------------- | | `ultra_low_latency` | `sonic-turbo` | 200ms | `backchannel` | 400ms | 1 sentence | Quick intake, high-volume triage, yes/no flows | | `balanced` | (default) | 500ms | (default) | (default) | (unlimited) | General-purpose conversations | | `quality` | `sonic-3` | 500ms | `phrase` | (default) | (unlimited) | Sensitive topics, empathetic conversations where natural speech quality matters more than speed | | `gpt_live` | n/a | n/a | n/a | n/a | n/a | Full-duplex model-family selection where enabled | | `gpt_realtime` | n/a | n/a | n/a | n/a | n/a | Realtime speech-to-speech provider selection where enabled | Presets are a starting point. You can apply a preset and then override individual fields on top of it. ## API Usage Voice config is a field on the service model. You set it when creating or updating a service. ### Setting voice config via PUT {% openapi src="" path="/v1/{workspace\_id}/services/{service\_id}" method="put" %} {% endopenapi %} ```json { "voice_config": { "tts_model": "sonic-turbo", "max_buffer_delay_ms": 200, "filler_style": "backchannel", "backchannel_delay_ms": 400, "max_response_sentences": 1, "barge_in_min_speech_s": 0.25, "forward_call_enabled": false } } ``` The `voice_config` object is replaced wholesale, not merged. Merge behavior on service update applies only across other top-level service fields - within `voice_config`, whatever you send becomes the entire config. To change one field, send the full object: read the current config via `GET`, modify the field, and `PUT` the complete object back. A partial body like this: ```json { "voice_config": { "filler_style": "silent" } } ``` changes the filler style, but it also drops every omitted nullable field (`tts_model`, `max_buffer_delay_ms`, and so on return to their field-specific inheritance or runtime defaults) and resets defaulted fields to their defaults (`backchannel_delay_ms` to `400`, `forward_call_enabled` to `false`). ### Reading current config The service response includes the full `voice_config` object: {% openapi src="" path="/v1/{workspace\_id}/services/{service\_id}" method="get" %} {% endopenapi %} ```json { "id": "svc_abc123", "name": "Intake Line", "voice_config": { "tts_model": "sonic-turbo", "max_buffer_delay_ms": 200, "filler_style": "backchannel", "filler_vocabulary": null, "backchannel_delay_ms": 400, "eager_eot_threshold": null, "eot_timeout_ms": null, "max_response_sentences": 1, "max_response_words": null, "barge_in_min_speech_s": 0.25, "barge_in_cooldown_s": null, "forward_call_enabled": false } } ``` Fields that are `null` apply no service-level override. Depending on the field, the runtime then consults agent, workspace, or environment configuration, or uses a runtime default. See [Field-Specific Resolution](#field-specific-resolution). ## CLI Usage The `forge` CLI provides a shorthand for voice config operations. ### Apply a preset ```bash forge platform service voice-config --preset ultra_low_latency ``` This sets all the fields in the preset at once. ### Set individual fields ```bash forge platform service voice-config \ --body '{"filler_style": "silent", "max_response_sentences": 1}' ``` ### Read current config ```bash forge platform service voice-config --get ``` ## Field-Specific Resolution Voice settings do not use one universal first-non-null cascade. Resolution depends on the field: | Configuration | Resolution order | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session provider | Service, then agent, then environment | | Flat TTS provider | Service, then agent, then workspace, then environment | | Per-language TTS provider | Exact language, base language, then `multilingual`; for each key, service, then agent, then workspace | | TTS provider configuration and model | Workspace settings form the base, agent `tts_config` overrides them, and service `tts_config` overrides both. A service `tts_model` is the final model override; unresolved values use the environment configuration. When a per-language entry selects the provider, that entry's config replaces the merged base provider config | | Service tuning fields | The service value applies when set; otherwise the field's documented runtime default or supported fallback applies | ### Workspace Voice Settings Workspace Voice Settings provide baseline voice identity, tone, speed, volume, language, keyterms, and sensitive topics. See [Workspaces](/developer-guide/platform-api/workspaces.md#voice-settings) for how those settings interact with service overrides. {% openapi src="" path="/v1/{workspace\_id}/settings/voice" method="get" %} {% endopenapi %} {% openapi src="" path="/v1/{workspace\_id}/settings/voice" method="put" %} {% endopenapi %} Context Graph `TurnPolicy` and channel overrides control separate state- and channel-specific behavior. They can gate capabilities or alter objectives and guidance, but they are not additional tiers in a generic voice-setting cascade. ## Turn-Level Emotion Selection During each turn, the voice pipeline selects an emotional tone alongside the state transition, based on the caller's emotional state and the conversation context. The selected tone is applied to the entire response - the filler and the main response share it - so each turn is spoken with one consistent voice. ### Available Emotions The pipeline chooses from eight emotions: | Emotion | When to use | | -------------- | -------------------------------------------------------------------------- | | `friendly` | Default warmth. General conversations, greetings, confirmations. | | `sympathetic` | Caller is frustrated, upset, or sharing bad news. | | `calm` | Sensitive topics, de-escalation, anxious callers. | | `enthusiastic` | Positive outcomes, good news, caller is excited. | | `serious` | Important information, disclaimers, medical details. | | `cheerful` | Light conversations, small talk, closing on a positive note. | | `curious` | Asking clarifying questions, exploring a topic. | | `content` | Neutral satisfaction. Wrapping up, confirmations after a good interaction. | Because the tone applies to the whole utterance, the prosody stays consistent from the first filler word to the end of the response - there are no uncanny emotional shifts partway through a sentence. The empathy system can override the turn-level selection at higher tiers. At Tier 2 (full empathy), the system forces warmth regardless of the selected emotion. At Tier 3 (hold space), filler is suppressed entirely and silence replaces speech. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/workspaces/voice-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.