> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md).

# Voice Configuration

Configure per-service voice latency, fillers, barge-in, response limits, provider inheritance, call forwarding, and conversation tool availability.

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 > `concurrence`. `tts_provider` resolves service > agent > workspace, and with none named the [Default TTS Model](#default-tts-model) rule picks the provider. 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.

## Choosing a Realtime Voice Family

Choose the family for the service's channels and workflow. The `concurrence` cascade separates speech recognition, Concurrence reasoning, and speech generation. `gpt_realtime` supports one action state or a graph of 2 to 12 action states. `eleven_realtime` requires exactly one action state. `gpt_live` combines realtime speech with Concurrence reasoning and multi-state Context Graph navigation. `grok_voice` runs xAI's Grok Voice on exactly one action state. To see which families a workspace can use, with their models, voices, and settings, use [voice family discovery](#discover-voice-families).

| Capability                 | `concurrence` cascade                                            | `gpt_realtime`                                                             | `eleven_realtime`                                        | `gpt_live`                                               | `grok_voice`                                             |
| -------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
| Channels                   | Inbound phone, Playground, test calls                            | App voice session, inbound phone, Playground, test calls                   | App voice session, inbound phone, Playground, test calls | App voice session, inbound phone, Playground, test calls | App voice session, inbound phone, Playground, test calls |
| Regions                    | Workspace regions, subject to data residency policy              | Workspace regions, subject to data residency policy                        | Workspace regions. Requires `data_residency: "any"`      | US only. Requires `data_residency: "any"`                | Workspace regions. Requires `data_residency: "any"`      |
| Multi-state Context Graphs | Yes                                                              | Yes, with 2 to 12 action states with unique names and valid exit targets   | No, exactly one action state                             | Yes. Concurrence reasoning navigates delegated requests  | No, exactly one action state                             |
| Dynamic behaviors          | Yes                                                              | Yes                                                                        | No                                                       | Yes                                                      | No                                                       |
| Phone transfers            | Cold and warm                                                    | Cold and warm                                                              | Cold                                                     | Cold only                                                | Cold only                                                |
| End call                   | Yes                                                              | Yes                                                                        | Yes                                                      | Yes                                                      | Yes                                                      |
| Outbound calls             | Yes                                                              | Single-state graphs only                                                   | No                                                       | No                                                       | No                                                       |
| Operator takeover          | Yes, on supported phone calls                                    | No                                                                         | No                                                       | No                                                       | No                                                       |
| When to pick it            | Multi-state workflows and separate speech and reasoning controls | A speech-to-speech workflow with one state or a bounded action-state graph | A single-state workflow in an ElevenLabs voice           | Realtime speech with a multi-state Concurrence workflow  | A single-state workflow in a built-in Grok voice         |

App voice sessions use the [hold-to-talk app protocol](https://docs.concurrence.com/developer-guide/guides/app-voice-session.md). Phone transfers need a provisioned phone channel and [forwarding configuration](#call-forwarding). Browser sessions do not dial a transfer destination. Region availability does not establish regional data residency. See [Regional Coverage and Data Residency](https://docs.concurrence.com/platform-overview/data-residency).

For `gpt_realtime`, save one action state or 2 to 12 action states with unique names and exit targets that exist in the graph. On a multi-state graph, set both `new_user_initial_state` and `returning_user_initial_state` to the first state's name. `gpt_realtime` runs the enabled [dynamic behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors.md#services-on-gpt-realtime) that the service's version set pins. For `eleven_realtime`, save exactly one action state, with no enabled dynamic behaviors, including enabled library behavior pins, and no tool call spec that sets `navigate_on_completion`. Neither family accepts typed `guardrails` on an action state: move each rule to the state's `boundary_constraints`. See [Session Provider](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#session-provider) for save refusals.

A call on a version set whose agent version runs a [direct program](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md) runs no Context Graph. Among the voice families, only `grok_voice` runs a direct program, on app voice sessions and on Playground and test calls. A phone call to a service whose version set runs a direct program takes the safe exit, with code `direct_program_phone_line` on a `grok_voice` service (`direct_program_released_harness` when its voice harness is a registered release). Every other family runs a Context Graph.

### Discover Voice Families

Read families, models, voices, and settings from the Platform API instead of hard-coding them. The lists depend on the workspace and can change.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/voice-families" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The response lists every family, including families the workspace cannot use, and any workspace role can read it. For each family:

* `id` is the value for `voice_config.session_provider`.
* `availability.available` says whether this workspace can use the family. When it is `false`, `availability.reason` gives a `code` and `message` that explain why.
* `capabilities` describes what the family supports, such as its channels, multi-state graphs, dynamic behaviors, outbound calls, warm transfer, operator takeover, and end call.
* `config_key` names the `voice_config` block that holds the family's settings, such as `gpt_live`. `legacy_keys` lists other `voice_config` keys that belong to the family. `concurrence` has no block.
* `honored_settings` lists the service settings the family reads, as dotted paths from the service, such as `keyterms` and `voice_config.silence_policy`. A save that sets any other setting is accepted, and the family ignores it.
* `models` lists the family's model ids, and `options` is the JSON Schema for its block.
* `voices.path` is the route that lists the family's voices. `voices.listing` is `static` for a built-in list or `vendor` for a list read from the voice provider. `concurrence` has no voice list. Its voices are agent-level speech settings.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/voice-families/{family}/voices" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The voices route pages a family's voices, also for a family the workspace cannot use. Pass `next_cursor` back as `cursor`, with the same filters, to read the next page. Built-in voices have no language, so a `language` filter returns no `gpt_realtime`, `gpt_live`, or `grok_voice` voices. `eleven_realtime` voices come from ElevenLabs, which applies the filters and paging. A `502` with `voice_catalog_unavailable` means the list could not be read, so retry later. Asking for `concurrence` voices returns `404` with `voices_not_listed`.

To switch a service to a family, set `voice_config.session_provider` to its `id` and put its settings in the block its `config_key` names. Remove the keys that every other family lists in `config_key` and `legacy_keys`: a save that keeps another family's block returns `422`.

### GPT Realtime Multi-State Workflows

A multi-state `gpt_realtime` session starts in the first action state. The model reasons from the current state's instructions and tools, with the graph's global guidance and call controls. It is offered `change_state` with the current state's exits and their conditions. When it requests an allowed move, the platform applies the change and waits for the voice provider to acknowledge the new instructions and tools before continuing.

Moves depend on the model: it can miss an exit and stay in the current state. Write clear exit conditions and test representative caller requests and returns to earlier states. A state without an exit to another state has no `change_state` tool. Entering a terminal state does not itself end the call.

`preload`, `wait_for`, `surface_spec_template`, `turn_policy`, and `channel_overrides` have no effect on `gpt_realtime`. A successful save does not make those fields apply. Use the platform-managed runtime for workflows that depend on them. Multi-state graphs serve inbound phone calls, app voice sessions, Playground, and test calls. Outbound `gpt_realtime` calls require a single action state.

### Eleven Realtime

Set `voice_config.session_provider` to `eleven_realtime` on the service and include the `eleven_realtime` block:

```json
{
  "voice_config": {
    "session_provider": "eleven_realtime",
    "eleven_realtime": {
      "voice": "YOUR_VOICE_ID",
      "model": "eleven_realtime_v1_mini"
    }
  }
}
```

`voice` is required: 1 to 64 letters, digits, underscores, or hyphens. `model` is optional, and its supported value and default are `eleven_realtime_v1_mini`. Select this family on the service, not the agent version. Send the block only with `session_provider: "eleven_realtime"`, and remove it when selecting another family. When updating, retain every other setting you need because `voice_config` is [replaced as a whole](#setting-voice-config-via-put).

Eleven Realtime serves app voice sessions, inbound phone calls, the Playground, and test calls. Phone calls can end or cold-transfer through the same call controls as `gpt_realtime`. Cold transfer is the supported transfer mode on this family, so set `warm_transfer` to `false` in the forwarding block. Outbound calls are not available. Workspaces with `data_residency: "regional"` cannot use this family.

The opening speaks the AI and recording notice in the selected ElevenLabs voice before the greeting. For a service that needs the notice spoken word for word, prefer `gpt_realtime` and verify the opening with representative calls. Eleven Realtime sessions are recorded and billed as voice minutes, subject to the [test-traffic billing rules](https://docs.concurrence.com/testing/testing/playground#test-traffic-and-billing).

### GPT-Live

GPT-Live pairs OpenAI's GPT-Live, which listens and speaks, with Concurrence reasoning, which runs the conversation, its Context Graph, and its tools.

Set `voice_config.session_provider` to `gpt_live` on the service. The `gpt_live` block is optional: when it is absent, the session uses model `gpt-live-1` and voice `marin`. Include the block to choose the model or voice explicitly:

```bash
curl -X PUT "https://platform.api-us.concurrence.com/v1/{workspace_id}/services/{service_id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_config": {
      "session_provider": "gpt_live",
      "gpt_live": {
        "model": "gpt-live-1",
        "voice": "marin"
      }
    }
  }'
```

The request replaces the whole `voice_config`, so include every other voice setting the service keeps. See [Setting voice config via PUT](#setting-voice-config-via-put).

| Field in `gpt_live` | Values                                         | Default      |
| ------------------- | ---------------------------------------------- | ------------ |
| `model`             | `gpt-live-1` or `gpt-live-1.1-leopard-2-alpha` | `gpt-live-1` |
| `voice`             | A voice `id` from the GPT-Live voices list     | `marin`      |

`gpt-live-1.1-leopard-2-alpha` is OpenAI's GPT-Live 1.1 multilingual alpha. It targets English, Spanish, Portuguese, Chinese, French, German, Hindi, Japanese, and Korean first. A service runs it only when its `gpt_live.model` names it:

```json
{
  "voice_config": {
    "session_provider": "gpt_live",
    "gpt_live": {
      "model": "gpt-live-1.1-leopard-2-alpha"
    }
  }
}
```

Its behavior and availability follow OpenAI's alpha and can change. Test representative calls in each language your callers speak before moving a production service to it, and keep `gpt-live-1` on services that need a stable model.

List the voices with `GET /v1/{workspace_id}/voice-families/gpt_live/voices`, described in [Discover Voice Families](#discover-voice-families). Each voice's `id` is a value for `gpt_live.voice`.

These are the block's only fields. Unknown fields or unsupported model or voice values return `422`. The language comes from the agent's instructions. Select this family on the service, not an agent version, and send the `gpt_live` block only with `session_provider: "gpt_live"`. When switching from another family, remove its blocks as described in [Discover Voice Families](#discover-voice-families).

GPT-Live serves app voice sessions, inbound phone calls, Playground, and test calls in US workspaces with `data_residency: "any"`. Other regions and workspaces with regional data residency are refused. In those workspaces, discovery reports GPT-Live as unavailable, with the same `code` and `message` that a save returns, and lists no models. Concurrence reasoning navigates multi-state Context Graphs for delegated requests. Dynamic behaviors and services with tools that can make changes are supported.

GPT-Live is the voice front end. Concurrence reasoning answers every delegated request, including tool calls, policy checks, and the answer text, with the workspace's `voice.text_model`, or the platform default model when it is unset. See [Workspace Voice Settings](#workspace-voice-settings). The `gpt_live.model` setting selects the voice model only.

The voice model answers greetings, thanks, and brief clarifications itself. It is instructed to delegate requests to save, add, mark, list, read, or look up information through the service's tools, and to wait for results before answering. Graph navigation and tool execution happen on delegated requests. Test representative requests and corrections to check that the intended workflow runs. GPT-Live is instructed not to give medical, legal, or financial advice and to suggest asking a professional.

Phone calls support end call and cold transfer. Configure forwarding with `warm_transfer: false`. A save with `warm_transfer: true` is refused. Warm transfer, outbound calls, and operator takeover are not available. App and browser sessions do not dial a transfer destination.

The opening AI and recording notice, emergency scripts, and a small set of fixed lines use prerecorded audio. The caller cannot interrupt a prerecorded line while it plays, and speech during that line is not processed. The timeout line is English only. The conversation uses the selected GPT-Live voice. Sessions are recorded and billed as voice minutes, subject to the [test-traffic billing rules](https://docs.concurrence.com/testing/testing/playground#test-traffic-and-billing).

#### GPT-Live Save Refusals

A refused save returns `422` with `detail.code` and `detail.message`. Show the message to the person configuring the service:

| `detail.code`                         | `detail.message`                                                                                                                                                  | What to do                                                                                                                                               |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gpt_live_agent_version_unsupported`  | An agent version cannot select gpt\_live. Set voice\_config.session\_provider and voice\_config.gpt\_live on the service.                                         | Select the family on the service. Its model and voice block is optional.                                                                                 |
| `gpt_live_region_unsupported`         | GPT-Live is US only for now.                                                                                                                                      | Use a US workspace, or choose another family.                                                                                                            |
| `gpt_live_data_residency_unsupported` | GPT-Live is not available to a workspace with regional data residency.                                                                                            | Choose a family that meets the workspace's residency policy.                                                                                             |
| `family_warm_transfer_unsupported`    | This voice family does not support warm transfer. Set forwarding.warm\_transfer to false.                                                                         | Set `voice_config.forwarding.warm_transfer` to `false`.                                                                                                  |
| `family_cannot_speak_service_lines`   | This voice family uses reviewed audio clips and cannot speak service-written lines. Clear these overrides or choose a family that supports service-written lines. | Clear the settings that `detail.fields` names, such as `voice_config.filler_vocabulary` or `voice_config.progress_vocabulary`, or choose another family. |

The two `family_` refusals also return `detail.fields`, the settings to change. They also apply when saving a Context Graph or agent version that a GPT-Live service uses.

A schema validation error has a list of problems in `detail` instead. App session admission also checks availability: see [GPT-Live start refusals](https://docs.concurrence.com/developer-guide/guides/app-voice-session.md#start-a-session).

### Instruction Size

A realtime family accepts instructions only up to its model's limit, and the platform checks the size when you create or update a service. The size is rendered from the agent's identity and the Context Graph, so it covers every action state, not only the text you edit in the service. The token count is an estimate, so a service close to a limit can be refused slightly before or after the vendor would count it.

| Family                                          | Limit                        |
| ----------------------------------------------- | ---------------------------- |
| `gpt_live`                                      | 16,384 tokens for each model |
| `gpt_realtime`, `eleven_realtime`, `grok_voice` | About 128,000 tokens         |

A service over its family's limit is not saved. The response is `422` with `instructions_over_limit`, and the message names the version set, the family, the instruction size, and the limit. A service that leaves its model unset is held to the lowest limit among its family's models. Shorten the persona, the state instructions, or the boundary guidance, or move detail into tools and knowledge the agent looks up when needed.

### Grok Voice

Grok Voice runs the call on xAI's Grok Voice speech-to-speech model, which listens to the caller and answers in a built-in Grok voice. The model follows the Context Graph's one action state and calls its tools. The platform runs the call controls, the opening notice, the emergency scripts, and the [safe exit](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#graceful-degradation).

Set `voice_config.session_provider` to `grok_voice` on the service. The `grok_voice` block is optional: when it is absent, the session uses model `grok-voice-3.0`, voice `eve`, normal speed, and reasoning effort `none`. Include the block to choose these settings or to add transcription hints:

```bash
curl -X PUT "https://platform.api-us.concurrence.com/v1/{workspace_id}/services/{service_id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_config": {
      "session_provider": "grok_voice",
      "grok_voice": {
        "model": "grok-voice-3.0",
        "voice": "eve",
        "speed": 1.0,
        "reasoning_effort": "none",
        "keyterms": ["Dr. Ramirez", "metformin"],
        "language_hint": "en"
      }
    }
  }'
```

The request replaces the whole `voice_config`, so include every other voice setting the service keeps. See [Setting voice config via PUT](#setting-voice-config-via-put).

| Field in `grok_voice` | Values                                                                                                                                         | Default                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `model`               | `grok-voice-3.0`                                                                                                                               | `grok-voice-3.0`                                                       |
| `voice`               | A voice `id` from the Grok Voice voices list                                                                                                   | `eve`                                                                  |
| `speed`               | A number from 0.7 to 1.5                                                                                                                       | Normal speed, 1.0                                                      |
| `reasoning_effort`    | `none` or `high`                                                                                                                               | `none`                                                                 |
| `keyterms`            | Up to 100 terms, each 1 to 50 characters                                                                                                       | The service's `keyterms`                                               |
| `language_hint`       | `en`, `ar-EG`, `ar-SA`, `ar-AE`, `bn`, `zh`, `fr`, `de`, `hi`, `id`, `it`, `ja`, `ko`, `pt-BR`, `pt-PT`, `ru`, `es-MX`, `es-ES`, `tr`, or `vi` | `es-MX` for an agent whose default language is Spanish, otherwise none |

`speed` sets how fast the voice speaks: below 1.0 is slower, above 1.0 is faster. `reasoning_effort` turns the model's reasoning off (`none`) or on (`high`). Test response timing on representative calls before you turn it on.

`keyterms` are transcription hints for names and domain words the caller says. When `keyterms` is unset, the session sends the service's own `keyterms`, up to the first 100, each shortened to 50 characters. Workspace keyterms are not added, and an empty list sends no hints. `language_hint` biases transcription of the caller toward one language. Leave it unset for a multilingual agent. It does not change the language the agent speaks, which comes from the agent's instructions.

List the voices with `GET /v1/{workspace_id}/voice-families/grok_voice/voices`, described in [Discover Voice Families](#discover-voice-families). Each voice's `id` is a value for `grok_voice.voice`. A save accepts a voice in any letter case and stores it in lowercase.

These are the block's only fields. Unknown fields, unlisted `model`, `voice`, or `language_hint` values, a `speed` outside 0.7 to 1.5, and `keyterms` outside those limits return `422`. Select this family on the service, not an agent version, and send the `grok_voice` block only with `session_provider: "grok_voice"`. When switching from another family, remove its blocks as described in [Discover Voice Families](#discover-voice-families).

Grok Voice serves app voice sessions, inbound phone calls, Playground, and test calls in workspaces with `data_residency: "any"`. A workspace with regional data residency is refused: a save that selects the family returns `grok_voice_not_enabled`, discovery reports the family as unavailable with the same `code` and `message`, an [app session start](https://docs.concurrence.com/developer-guide/guides/app-voice-session.md#start-a-session) returns `403` with the same code, and a phone call takes the safe exit. A workspace's `data_residency` cannot be set to `regional` while one of its services is on `grok_voice`: the request returns `422` with `detail.code` `data_residency_refused`.

The Context Graph must be exactly one action state, with no `guardrails` and no tool call spec that sets `navigate_on_completion`. A save is refused when the service would run enabled dynamic behaviors, including enabled library behavior pins. Phone calls support end call and cold transfer through `forward_call`. Configure forwarding with `warm_transfer: false`, because a save with `warm_transfer: true` is refused. Warm transfer, outbound calls, and operator takeover are not available: an [outbound call](https://docs.concurrence.com/developer-guide/platform-api/conversations/calls.md) request whose use case's service runs on `grok_voice` returns `422` and dials nothing. App and browser sessions do not dial a transfer destination. A test call must use the `inbound` [scenario](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#test-call-scenarios), where the agent speaks first. A `silent` test call closes with `4200` before it starts.

Grok Voice also runs a [direct program](https://docs.concurrence.com/developer-guide/platform-api/workspaces/direct-programs.md#grok-voice), an agent version's own instructions and tool grants with no Context Graph, on app voice sessions and on Playground and test calls. A phone call to a service whose version set runs a direct program takes the safe exit, with code `direct_program_phone_line` on a `grok_voice` service (`direct_program_released_harness` when its voice harness is a registered release).

The opening AI and recording notice, emergency scripts, and a small set of fixed lines use prerecorded audio, not the selected Grok voice. The rest of the conversation uses the selected Grok voice. Sessions are recorded and billed as voice minutes, subject to the [test-traffic billing rules](https://docs.concurrence.com/testing/testing/playground#test-traffic-and-billing).

#### Grok Voice Save Refusals

A refused save returns `422` with `detail.code` and `detail.message`. Show the message to the person configuring the service:

| `detail.code`                                | `detail.message`                                                                                                                                                      | What to do                                                                                                                                               |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grok_voice_agent_version_unsupported`       | An agent version cannot select grok\_voice, because its voice is a service setting. Set voice\_config.session\_provider and voice\_config.grok\_voice on the service. | Select the family on the service. Its `grok_voice` block is optional.                                                                                    |
| `grok_voice_not_enabled`                     | grok\_voice is not available to a workspace with regional data residency                                                                                              | Choose a family that meets the workspace's residency policy.                                                                                             |
| `family_warm_transfer_unsupported`           | This voice family does not support warm transfer. Set forwarding.warm\_transfer to false.                                                                             | Set `voice_config.forwarding.warm_transfer` to `false`.                                                                                                  |
| `family_cannot_speak_service_lines`          | This voice family uses reviewed audio clips and cannot speak service-written lines. Clear these overrides or choose a family that supports service-written lines.     | Clear the settings that `detail.fields` names, such as `voice_config.filler_vocabulary` or `voice_config.progress_vocabulary`, or choose another family. |
| `realtime_guardrails_unsupported`            | Begins `grok_voice enforces no guardrails, but` and names the version set, the Context Graph, and its guardrails.                                                     | Move each rule to the state's `boundary_constraints`, bind a graph version without guardrails, or choose `concurrence`.                                  |
| `realtime_completion_navigation_unsupported` | Begins `grok_voice does not support navigate_on_completion, but` and names the action state and tool.                                                                 | Turn off `navigate_on_completion`, or choose `concurrence`.                                                                                              |

The two `family_` refusals also return `detail.fields`, the settings to change. They also apply when saving a Context Graph or agent version that a Grok Voice service uses.

A save that pairs the service with a Context Graph that is not exactly one action state, or with enabled dynamic behaviors, returns `422` with a plain string as `detail`. The graph refusal begins `grok_voice needs a context graph that is exactly one ActionState, but` and the behavior refusal begins `grok_voice runs no dynamic behaviors, but`. Each names the version set and what to change. A schema validation error has a list of problems in `detail` instead. App session admission also checks availability: see [Start a Session](https://docs.concurrence.com/developer-guide/guides/app-voice-session.md#start-a-session).

## Field Reference

### Latency

These fields control how quickly the agent responds after the caller stops speaking.

| Field                    | Type              | Default   | Description                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 | Confidence at which the recognizer reports an early end of turn. The agent replies at the final end of turn, so this value does not change when it responds. Applies on the platform-managed runtime, on recognizers that accept it. An English call on the default recognizer ignores it.                                                      |
| `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. Applies on the platform-managed runtime, on recognizers that accept it. An English call on the default recognizer ignores it. |
| `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 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, and 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.                                                                                                                                                                                                                                                                                                                            |

`progress_vocabulary` and `progress_interval_ms` apply on the platform-managed and `gpt_realtime` runtimes: a `gpt_realtime` caller waiting on a tool hears the same progress lines, following the graph's progress hints, and a `silent` hint stays silent there too. The other filler fields, `filler_style` included, apply only on the platform-managed runtime. On `gpt_realtime`, a multilingual agent says each built-in progress line in English, then Spanish. See [Tool-Wait Progress Hints](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#tool-wait-progress-hints).

Built-in fillers and progress lines play in the voice's language, English or Spanish, and a voice language without built-in fillers gets none. Your own filler text, from `filler_vocabulary`, `progress_vocabulary`, or Context Graph hints and phrases, plays only while the voice speaks the language the call started in. If custom fillers matter in more than one language, test them with a caller who switches languages. See [Language Selection](https://docs.concurrence.com/channels/voice/audio-pipeline#language-selection).

### Response

Response limits are applied while generated text is consumed. Sentence counting is approximate across streamed fragments, so these settings are not exact bounds on an utterance a caller will hear.

| Field                    | Type  | Default          | Description                                                                        |
| ------------------------ | ----- | ---------------- | ---------------------------------------------------------------------------------- |
| `max_response_sentences` | `int` | null (unlimited) | Streamed-response sentence cap. Counting is approximate across streamed fragments. |
| `max_response_words`     | `int` | null (unlimited) | Streamed-response word cap, enforced while consuming generated text.               |

### Barge-in

Barge-in is when caller speech cuts the agent off. On the platform-managed runtime, one rule decides it, for the greeting and for every later reply.

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-926797a7e862cf84a268ab1a16eb3c482e2d8417%2Fbarge-in-rule.svg?alt=media" alt="On the platform-managed runtime, caller speech cuts the agent off only when the state&#x27;s turn policy allows it and the speech has recognized words; speech still in progress also needs a minimum duration and a cooldown. The call-opening notice always plays to the end."><figcaption><p>On the platform-managed runtime, the same rule covers the greeting and every later reply.</p></figcaption></figure>

* The active state's turn policy must allow barge-in. `barge_in_enabled` is on by default. Turn it off in a state whose replies must play in full, such as a consent read-out.
* A finished caller utterance with recognized words takes the floor at once, with no minimum duration and no cooldown, except over the notice below.
* Speech still in progress takes the floor only with recognized words, at least `barge_in_min_speech_s` of speech, and at least `barge_in_cooldown_s` after the caller last cut the agent off. Sound with no recognized words, such as breathing or background noise, does not interrupt, although background speech and recognition errors can.
* The [call-opening notice](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#call-opening) always plays to the end, and speech still in progress waits until it has played. A finished utterance spoken over the notice is answered once the notice ends, instead of the greeting or reply that would have played next.

When the caller takes the floor, the agent's audio stops and nothing more of that reply plays. Conversation history keeps the interrupted reply only up to the words the caller heard, so the next turn reasons from what the caller actually heard. The trim uses word timing from the voice provider and is best-effort.

On `gpt_realtime`, `realtime.turn_detection` decides when the caller's turn starts and ends, and these rules decide when a reply is cut off:

* After the [call opening](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#call-opening), a reply is cut off once the realtime session has reported the caller's speech over it for `barge_in_min_speech_s`. The minimum counts the speech the session detects, not recognized words, and `barge_in_cooldown_s` does not apply.
* Speech over the notice and the greeting does not cut them off. It is answered after they finish, unless the platform recognizes the caller's words as a medical emergency or self-harm, in English or Spanish. See [Realtime Emergency Script](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#realtime-emergency-script).
* A state's turn policy does not apply, so `barge_in_enabled` has no effect.
* With `server_vad`, which detects speech by volume and is the default when `realtime.turn_detection` is unset, the session reports speech as stopped only after `realtime.turn_detection.silence_duration_ms` of silence (200 to 3000 milliseconds, 500 unless set), so a sound counts for its length plus that silence. With `semantic_vad`, the session decides from the words when the caller is done, so the time before it reports speech as stopped varies with what was said and there is no fixed silence to add. Apart from a line the platform recognizes as a medical emergency or self-harm, which cuts a reply once its words are transcribed whatever the minimum (see [Realtime Emergency Script](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#realtime-emergency-script)), speech reported as stopped before the minimum cuts nothing, even a finished utterance. To let a reply play through sounds up to a given length with `server_vad`, set `barge_in_min_speech_s`, in seconds, above that length plus the silence, which is in milliseconds: at the default 500 milliseconds, a value of 1.0 lets a reply play through sounds shorter than half a second. A short interruption, such as a one-word "stop", then cuts nothing either.

| Field                   | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `barge_in_min_speech_s` | `float` | `0.5`   | Minimum duration of speech still in progress before it can cut the agent off. On the platform-managed runtime the speech also needs recognized words, and a finished utterance with recognized words needs no minimum. On `gpt_realtime` the minimum counts all speech the realtime session detects, and speech it reports as stopped before the minimum cuts nothing, finished utterances included, an emergency line aside. Lower values let in-progress speech interrupt sooner. |
| `barge_in_cooldown_s`   | `float` | `1.5`   | Time after the caller last cut the agent off before speech still in progress can do so again. Prevents rapid back-and-forth interruptions. It applies only on the platform-managed runtime.                                                                                                                                                                                                                                                                                         |

### 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`   | `"concurrence"`, `"gpt_realtime"`, `"eleven_realtime"`, `"gpt_live"`, or `"grok_voice"` | inherited | Selects the voice family at the service level. Null inherits the agent value, then `concurrence`. See [Choosing a Realtime Voice Family](#choosing-a-realtime-voice-family) for channels, graph requirements, and call controls.                                                                                                   |
| `tts_provider`       | `"cartesia"` or `"elevenlabs"`                                                          | inherited | Overrides the TTS provider at the service level. Null inherits from the agent, then the workspace. See [Default TTS Model](#default-tts-model) when none is named.                                                                                                                                                                 |
| `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). Each key is a language code, such as `es` or `es-MX`, or `multilingual`. A call uses the entry for its exact language, then its base language, then `multilingual`. Workspace voice settings take only `en`, `es`, `ar`, `fr`, `de`, `pt`, `zh`, `ja`, `ko`, and `multilingual`. |
| `realtime`           | object                                                                                  | null      | Realtime session controls. Requires `session_provider` `gpt_realtime`. See [Realtime Session Models](#realtime-session-models).                                                                                                                                                                                                    |
| `eleven_realtime`    | object                                                                                  | null      | The required `voice` and optional `model` for `session_provider: "eleven_realtime"`. See [Eleven Realtime](#eleven-realtime).                                                                                                                                                                                                      |
| `gpt_live`           | object                                                                                  | null      | The GPT-Live `model` and `voice`, accepted only with `session_provider: "gpt_live"`. See [GPT-Live](#gpt-live).                                                                                                                                                                                                                    |
| `grok_voice`         | object                                                                                  | null      | The Grok Voice `model`, `voice`, `speed`, `reasoning_effort`, `keyterms`, and `language_hint`, accepted only with `session_provider: "grok_voice"`. See [Grok Voice](#grok-voice).                                                                                                                                                 |

### Realtime Session Models <a href="#realtime-session-models" id="realtime-session-models"></a>

On the `gpt_realtime` runtime, `realtime.model` accepts `gpt-realtime-2.1`, the default, and `gpt-realtime-2.1-mini`. Caller-audio transcription, `realtime.transcription.model`, accepts `gpt-transcribe`, which is also its default. Other ids return `422`, including `gpt-realtime-1.5`, `gpt-realtime-2`, `whisper-1`, `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`. `realtime.reasoning_effort` is accepted with either model.

`realtime.transcription.language` is optional. When set, it must match one of the codes the schema lists exactly, such as `en`, `es`, or `eng`, or the save returns `422`. The list holds lowercase two- and three-letter language codes plus `zh-cn`, `zh-hk`, and `zh-tw`, so `EN`, `en-US`, and `en-us` are refused. When it is unset, and the service does not serve English and Spanish from an English default, the caller is transcribed in the agent's default language (`identity.default_spoken_language`) when that language is one of the languages workspace voice settings take: `en`, `es`, `ar`, `fr`, `de`, `pt`, `zh`, `ja`, or `ko`. The agent's default language can also be spelled with three letters, such as `eng` or `spa`, as a language name such as `English`, or with a region tag such as `en-US`; only the `realtime.transcription.language` field itself is held to the exact codes above. For a service that serves English and Spanish from an English default (see [Languages a Service Serves](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#languages-a-service-serves)), the transcriber expects English or Spanish and leans toward English, so set this field when a service's callers mostly speak a language other than English. An agent with any other language gets transcription that detects the language as the caller speaks. The language the agent speaks comes from its instructions, not from this setting.

### Default TTS Model

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-242310b59873ed29ec174a07a7a2ac422737f35f%2Ftts-provider-model.svg?alt=media" alt="A call&#x27;s TTS provider comes from a matching language_providers entry, then a named tts_provider, then Cartesia when any TTS setting is stored, and otherwise ElevenLabs with its default voice. Each provider then uses a stored model or its default, and retired pins use the default."><figcaption><p>Retired pins keep their voice and other settings, and stored configuration is not rewritten. Voice notes always speak ElevenLabs, as described below.</p></figcaption></figure>

A live call picks its TTS provider in this order:

1. A `language_providers` entry for the call's language: the exact language, then its base language, then `multilingual`, checking the service, then the agent, then the workspace for each key. The entry brings only its own config.
2. A `tts_provider` named on the service, then the agent, then the workspace.
3. With no provider named, Cartesia when any TTS setting is stored: a workspace `voice_id`, `pronunciation_dict_id`, or `tts_config`, an agent `voice_config` with a `voice_id` or `tts_config`, or a service `tts_config`. With none of these stored, the call speaks ElevenLabs `eleven_v4_turbo` with the ElevenLabs default voice, Eldrin.

To keep an unconfigured service on Cartesia, set `tts_provider` to `cartesia`.

When the resolved configuration stores no model, Cartesia calls use Sonic 3.6 (`sonic-3.6-2026-08-27`), and ElevenLabs calls use `eleven_v4_turbo`.

A stored model, `tts_config.model` at the workspace, agent, or service level or a per-language entry's `config.model`, takes precedence over the default unless it is a retired id listed below. To keep a call on a specific model, pin it in the service `tts_config.model`. The service `voice_config.tts_model` field does not select a model: a request that sends it is accepted, but the value is ignored. A matching `language_providers` entry, including `multilingual`, brings only its own config, so pin the model in that entry's `config.model` too. An entry without one uses the default even when the base config pins a model.

Voice notes sent to the [voice-turn operation](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#process-a-voice-note-turn) always speak ElevenLabs. When a live call from the same caller would speak ElevenLabs, the reply uses that call's ElevenLabs voice and model, with `language_providers` matched on the language the note was spoken in. Otherwise the reply uses the ElevenLabs default voice, Eldrin, on `eleven_v4_turbo`.

#### Retired Cartesia Models <a href="#retired-cartesia-models" id="retired-cartesia-models"></a>

When the resolved Cartesia model is one of the ids below, the call uses Sonic 3.6 instead. Voice, speed, volume, tone, and language settings are kept, and the stored configuration is not rewritten.

The remap covers `sonic`, `sonic-english`, `sonic-multilingual`, `sonic-2024-10-19`, `sonic-2024-12-12`, `sonic-2` and its snapshots, `sonic-turbo` and its snapshots, `sonic-3-2025-10-27`, and the Sonic 3 and Sonic 3.5 ids `sonic-3`, `sonic-3-preview`, `sonic-3-2026-01-12`, `sonic-3.5`, and `sonic-3.5-2026-05-04`. `sonic-3.6`, `sonic-preview`, and ids the platform does not recognize are sent as stored.

This applies to every place a model can be stored. Replace these pins with a current model so the configuration shows what the call speaks.

#### Retired ElevenLabs Models <a href="#retired-elevenlabs-models" id="retired-elevenlabs-models"></a>

A stored ElevenLabs pin of `eleven_flash_v2_5`, `eleven_flash_v2`, `eleven_turbo_v2_5`, `eleven_turbo_v2`, `eleven_multilingual_v2`, `eleven_multilingual_v1`, or `eleven_monolingual_v1` uses `eleven_v4_turbo` instead, on live calls and voice notes. The voice and stored configuration are kept.

On live calls, ElevenLabs voices apply only `stability` from the voice settings. It defaults to 0.5, and configuration or a sympathetic tone can change it. `style` and `speed`, whether configured or emotion-driven, and stored `similarity_boost` and `use_speaker_boost` have no effect. Voice notes send no voice settings, so they use the voice's own. Test a service that depends on a slower or faster speaking rate.

ElevenLabs voice runs only `eleven_v3*` and `eleven_v4*` models. A stored model that is neither one of those nor a retired id listed above, for example a bare `v3`, `eleven_ttv_v3`, `eleven_english_sts_v2`, or a case variant such as `Eleven_v4_turbo`, fails the voice session at setup with an error naming the id, and a phone call then takes the [safe exit](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#graceful-degradation). Pin a current `eleven_v3*` or `eleven_v4*` id, or leave the model unset to use the default.

### Call Forwarding

A service destination, `fallback_to` included, must also be on the provisioned voice use case's `allowed_forwarding_numbers`. Confirm the [Channel Manager forwarding restrictions](https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md#control-voice-calls) before using transfers.

Configure forwarding in `voice_config.forwarding`. Omitting that block or setting it to null leaves the forwarding tool unavailable. When present, choose warm or cold transfer explicitly and configure either a fixed destination or dynamic destination mode. There is no workspace-number fallback.

A fixed destination sets `forward_to` to one E.164 number. Dynamic mode sets `forward_to` to null and lists every number `forward_call` may dial in `approved_destinations`, a map of E.164 number to a label for what answers there, such as `{"+16095550199": "Scheduling desk"}`, with up to 50 entries. The agent picks from those numbers and sees their labels. Any other number is refused without dialing, and a dynamic block with no approved destinations offers no `forward_call` tool. Setting `approved_destinations` with a fixed `forward_to` returns `422`. A number with an extension, such as `+16095550199x123`, returns `422` in either mode, so enter the direct number. A public emergency or N11 short code (211 through 911, and 988) is refused in `forward_to`, `approved_destinations`, and `fallback_to`, and `forward_call` does not dial one.

`fallback_to` is optional in both modes, including a dynamic block that approves no destinations. It names the line the [safe exit](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#graceful-degradation) dials, and no other transfer uses it. That transfer is cold. When the platform can't hand the caller off, for example because the number isn't on the use case's `allowed_forwarding_numbers`, the exit plays the closing line and ends the call instead of returning to the agent. Send a direct E.164 number with its country code, such as `+16095550142`. The platform stores the E.164 form, so `+1 609 555 4321` is stored as `+16095554321`. Send `null`, or leave the field out, for no fallback number. An empty or blank string returns `422`.

A `fallback_to` that is not a valid number with a country code returns `422` with the message `Value error, invalid phone number`, and one with a short extension, such as `+16095550199x123`, returns `422` with `Value error, phone number has an extension; enter the direct number`. A value longer than 16 characters once surrounding spaces are removed returns `422` too. These arrive in the standard validation list, with a `loc` that ends in `fallback_to`, and the response does not repeat the value. A save that names a number the platform does not accept as a destination returns `422`, and the message names `fallback_to` and not the number.

```json
{
  "forwarding": {
    "forward_to": null,
    "warm_transfer": true,
    "approved_destinations": {
      "+16095550199": "Scheduling desk",
      "+16095550123": "Billing office"
    },
    "fallback_to": "+16095550142"
  }
}
```

In the TypeScript SDK, `@amigo-ai/platform-sdk` 0.125.0 and later types `fallback_to`. An update replaces the stored `voice_config`, so spread the current one into the request:

```typescript
const service = await client.services.get(serviceId)

await client.services.update(serviceId, {
  voice_config: {
    ...service.voice_config,
    forwarding: {
      forward_to: null,
      warm_transfer: true,
      approved_destinations: {
        '+16095550199': 'Scheduling desk',
        '+16095550123': 'Billing office',
      },
      fallback_to: '+16095550142',
    },
  },
})
```

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-300ba91c4b951afc69db378d1ab03ddc00d94b3e%2Ftransfer-resolution.svg?alt=media" alt="The forwarding block offers forward_call to a fixed number or, in dynamic mode, only to approved destinations, and each must be on the line&#x27;s allowlist. A transfer that can&#x27;t connect, including a warm transfer that misses, fails, or loses the person who answered before the hand-off, returns the caller to the agent."><figcaption><p>A null or omitted <code>forwarding</code> block offers no <code>forward_call</code>, and there is no workspace fallback number.</p></figcaption></figure>

A cold transfer by `forward_call` hands the caller to the destination. A warm transfer connects once a person answers and the agent briefs them. A cold transfer can't connect when it can't hand the caller off, for example because the destination isn't on the line's forwarding allowlist. A warm transfer can't connect when it reaches voicemail, a fax, no answer, or a failed dial, or when the person who answered hangs up before the hand-off. Either way, the caller stays on the call with the agent, which is told to let them know and keep helping. The transfer sequence applies on `concurrence`, `gpt_realtime`, and `eleven_realtime`. Author the agent's instructions for a transfer that can't connect, and test them.

The `forwarding` block is the enablement control. There is no separate `forward_call_enabled` flag. The embedded service schema is authoritative for the forwarding object. On the platform-managed runtime, active turn policy can further restrict forwarding. See [Call Forwarding](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#call-forwarding) for the hold and answer-handling sequence.

#### Transfer Hours

`forwarding.hours` sets when the people who answer the service's lines are available. Omit it or send `null` to apply no staffed-hours check. It is an object with these fields:

| Field                           | Type                                  | Default                      | Description                                                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timezone`                      | string, 1 to 64 characters            | Required when `hours` is set | The time zone the windows are read in, such as `America/New_York`.                                                                                                                                                               |
| `windows`                       | list, 1 to 50 items                   | Required when `hours` is set | Each item has a `day` (`mon` through `sun`), an `open` time, and a `close` time, both 24-hour `HH:MM`. `close` can be `24:00`. A window covers `open` up to, not including, `close`. A weekday with no window is closed all day. |
| `closed_dates`                  | list of `YYYY-MM-DD` dates, up to 100 | `[]`                         | Dates the service is closed for the whole day, whatever the windows say.                                                                                                                                                         |
| `closed_on_us_federal_holidays` | boolean                               | `false`                      | When `true`, the service is closed for the whole day on US federal holidays.                                                                                                                                                     |

On a dynamic service, a transfer made outside staffed hours dials `after_hours_destination`, whichever approved line the agent asked for. `after_hours_destination` takes an E.164 number, or `null` for none, and defaults to `null`. Like the other destination fields, it must pass the `allowed_forwarding_numbers` check described above.

#### Transfer Reasons and Default Line

On a dynamic service, `transfer_reasons` lists up to 20 reasons that the agent names on each `forward_call`. Each reason has:

* `key`: 2 to 63 characters, made of lowercase letters, digits, hyphens and underscores, starting and ending with a letter or digit, such as `billing-question`.
* `description`: up to 200 characters, describing when the reason applies.

The call record stores the key the agent named in its `reason` field. A service with no reasons, which is the default, records no reason.

`default_destination` is the E.164 number a transfer dials when it names no destination, on a dynamic service. It defaults to `null`, which sets no default line. Like the other destination fields, it must pass the `allowed_forwarding_numbers` check described above.

```json
{
  "forwarding": {
    "forward_to": null,
    "warm_transfer": true,
    "approved_destinations": {
      "+16095550199": "Scheduling desk",
      "+16095550123": "Billing office"
    },
    "default_destination": "+16095550199",
    "after_hours_destination": "+16095550177",
    "hours": {
      "timezone": "America/New_York",
      "windows": [
        { "day": "mon", "open": "09:00", "close": "17:00" },
        { "day": "tue", "open": "09:00", "close": "17:00" },
        { "day": "wed", "open": "09:00", "close": "17:00" },
        { "day": "thu", "open": "09:00", "close": "17:00" },
        { "day": "fri", "open": "09:00", "close": "17:00" }
      ],
      "closed_dates": ["2026-12-25"],
      "closed_on_us_federal_holidays": true
    },
    "transfer_reasons": [
      { "key": "scheduling", "description": "The caller wants to book, move or cancel an appointment." },
      { "key": "billing-question", "description": "The caller has a question about a bill." }
    ]
  }
}
```

## Concurrent Inbound Calls

Several phone lines can call one service at once, including lines you use to test it. Two limits admit inbound calls before an agent takes them:

* **Per service.** `voice_config.max_concurrent_calls` is the number of concurrent inbound calls the service holds. It is an integer from 1 to 100 and defaults to 60.
* **Per caller number.** `voice_config.max_calls_per_caller` is the number of concurrent inbound calls one caller number can hold while calling the service. It is an integer from 1 to 100 and defaults to 2. A caller number's calls are counted across all services, and the value on the service taking the new call applies. A withheld number is not treated as one caller, so only the service limit applies to it.

A call past either limit does not reach the agent. It goes to the service's human line, `forwarding.fallback_to`, else `forwarding.forward_to`. With neither, the caller hears the end line and the call is hung up. See [Call Forwarding](#call-forwarding) for the destination rules.

A workspace's registered test number is held to the workspace's test-call slots instead of the per-caller limit, so several test calls from it share those slots. The service limit still applies.

When the slot check itself is unavailable, calls are admitted without the limits.

## Authored Greeting

`POST /sessions/start` accepts an optional `greeting` for a web session (`channel_kind` `web`). It is a per-session field, not a `voice_config` field, so set it when you start the session. Omit it or send `null` and the agent greets the caller automatically. A greeting can be up to 2,000 characters. See [Start a Web Text Session](https://docs.concurrence.com/developer-guide/platform-api/conversations.md#start-a-web-text-session).

## Named Presets

Agent Forge exposes four 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` | (default) | 200ms        | `backchannel` | 400ms             | 1 sentence   | Quick intake, high-volume triage, yes/no flows                                                                                                                                                                                                                                              |
| `balanced`          | (default) | 500ms        | (default)     | (default)         | (unlimited)  | General-purpose conversations                                                                                                                                                                                                                                                               |
| `quality`           | (default) | 500ms        | `phrase`      | (default)         | (unlimited)  | Sensitive topics, empathetic conversations where natural speech quality matters more than speed                                                                                                                                                                                             |
| `gpt_realtime`      | n/a       | n/a          | n/a           | n/a               | n/a          | Realtime speech-to-speech provider selection where enabled. The save accepts one action state or 2 to 12 action states with unique names and valid exit targets. See [Session Provider](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#session-provider). |

Presets are a starting point. You can apply a preset and then override individual fields on top of it. Presets do not select a Cartesia model, so pin a model in `tts_config.model` when you need one.

## 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="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```json
{
  "voice_config": {
    "max_buffer_delay_ms": 200,
    "filler_style": "backchannel",
    "backchannel_delay_ms": 400,
    "max_response_sentences": 1,
    "barge_in_min_speech_s": 0.25,
    "forwarding": null
  }
}
```

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 (`max_buffer_delay_ms`, `eot_timeout_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`, `forwarding` to `null`).

### Reading current config

The service response includes the full `voice_config` object:

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/services/{service\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```json
{
  "id": "svc_abc123",
  "name": "Intake Line",
  "voice_config": {
    "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,
    "forwarding": null
  }
}
```

Fields that are `null` apply no service-level override. Depending on the field, the runtime then consults agent or workspace configuration, or uses a platform or runtime default. See [Field-Specific Resolution](#field-specific-resolution).

### Harness settings and promotion

Harness settings are a separate per-service configuration from `voice_config`, with their own Platform API operations. The settings schema lists what each harness the service runs declares, its voice harness included, and a save replaces the service's values. A key left out follows its harness default. See [Read and Save Harness Settings](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#read-and-save-harness-settings).

To store a version set, with harness pins and harness settings when needed, only while the configuration you reviewed still holds, see [Promote a Reviewed Configuration](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#promote-a-reviewed-configuration).

## CLI Usage

The `forge` CLI provides a shorthand for voice config operations.

### Apply a preset

```bash
forge platform service voice-config <service_id> --preset ultra_low_latency
```

This sets all the fields in the preset at once.

### Set individual fields

```bash
forge platform service voice-config <service_id> \
  --body '{"filler_style": "silent", "max_response_sentences": 1}'
```

### Read current config

```bash
forge platform service voice-config <service_id> --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 `concurrence`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Flat TTS provider                    | On the platform-managed runtime: service, then agent, then workspace. With none named, Cartesia when any TTS setting is stored, otherwise ElevenLabs. See [Default TTS Model](#default-tts-model)                                                                                                                                                                                                                                                                                                                                                        |
| Per-language TTS provider            | On the platform-managed runtime: exact language, base language, then `multilingual`. For each key, the order is service, then agent, then workspace                                                                                                                                                                                                                                                                                                                                                                                                      |
| TTS provider configuration and model | On the platform-managed runtime: workspace settings form the base, agent `tts_config` overrides them, and service `tts_config` overrides both. Unresolved values use the platform defaults. A workspace `voice_id` applies only when the call speaks Cartesia, and an agent `voice_id` only when the call speaks the agent's `tts_provider` (Cartesia when unset). When a per-language entry selects the provider, that entry's config replaces the merged base provider config                                                                          |
| Voice language                       | On the platform-managed runtime: the agent's default language, English when it names none, which the matched caller's record language replaces when the service serves it. A workspace `language` of `multilingual` starts each call in the agent's default language and follows the language the caller speaks. Any other workspace `language` does not set the language a call starts in. The voice can follow a caller who switches language. See [Language Selection](https://docs.concurrence.com/channels/voice/audio-pipeline#language-selection) |
| Service tuning fields                | The service value applies when set. Otherwise the field's documented runtime default or supported fallback applies                                                                                                                                                                                                                                                                                                                                                                                                                                       |

On `gpt_realtime`, the voice comes from `realtime.voice` and the call's language is the agent's default language, English when it is empty or not recognized. A service that serves English and Spanish from an English default runs the bilingual session instead. See [Languages a Service Serves](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#languages-a-service-serves).

### Voice Setting Warnings

The [Read Service Readiness](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services.md#read-service-readiness) response lists each voice family a version set runs under `families`. Each entry has `ignored_settings`: the service settings, as dotted paths from the service such as `keyterms` or `voice_config.max_buffer_delay_ms`, that the service sets to a non-default value and this family does not read. The list is advisory. The save still succeeds, and those fields have no effect on that family's calls.

### Workspace Voice Settings

Workspace Voice Settings provide baseline voice identity, tone, speed, volume, language, keyterms, and sensitive topics. See [Workspaces](https://docs.concurrence.com/developer-guide/platform-api/workspaces.md#voice-settings) for how those settings interact with service overrides.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/voice" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/voice" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% 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 conversation. 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 tier shapes the reply alongside the selected tone. At Tier 2 (full empathy), the reply opens with empathy before any task content. At Tier 3 (hold space), the agent holds a longer pause and the whole reply is empathy.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
