# Advanced Settings

Configure speech recognition, turn-taking, speech speed, background sounds, and input filtering in an Advanced Settings resource. Link it to one or more Assistants with `advancedSettingsId`.

## Overview

Each configuration object is optional. Omitted settings use the platform defaults documented on the individual settings pages.

An Advanced Settings resource groups five configuration objects:

- **STT** controls transcript accuracy: keyword biasing and silence-based endpointing.
- **VAD** controls turn-taking: when the system considers the user to be speaking, when it considers them done, and whether the user can interrupt the Assistant.
- **TTS** controls how the Assistant speaks: the speech speed.
- **Sounds** controls background audio: the sound played while the Assistant is working on a response.
- **Audio** controls input filtering: the noise cancellation applied to the caller's voice.

Assistants linked to the same resource share its configuration. To use a different configuration, change the Assistant's `advancedSettingsId`.

Supported settings depend on the Assistant's architecture and providers:

- On an **LLM + TTS + STT** pipeline, STT and TTS support depends on the selected providers.
- With an **STS (Speech-to-Speech)** model, the realtime provider normally detects speech and turns. `stt.endpointing` has no effect. `vad.endpointingMaxDelay` and `vad.minSpeechDuration` have no provider equivalent when provider-side turn detection is used. Support for other fields varies by model.
- On GPT Realtime and Gemini Live, disabling interruptions switches turn detection to local VAD, making local speech detection settings effective.
- An STS Assistant with a separate TTS model uses that TTS integration's supported speed setting.

Unsupported fields are ignored. A configuration can save successfully for both pipeline and STS Assistants while producing different behaviour. See [STT Settings](/docs/stt-settings) and [VAD Settings](/docs/vad-settings) for provider support.

<Mermaid chart={`flowchart TD
    A1[Assistant A] --> AS[Advanced Settings]
    A2[Assistant B] --> AS
    A3[Assistant C] --> AS`} />

***

## Data model

| Field         | Type   | Required       | Description                                                             |
| ------------- | ------ | -------------- | ----------------------------------------------------------------------- |
| `id`          | uuid   | Auto-generated | Unique identifier                                                       |
| `name`        | string | Yes            | Descriptive label for the configuration                                 |
| `description` | string | No             | Free-text explanation of the configuration's purpose                    |
| `stt`         | object | No             | Speech-to-text settings. See [STT Settings](/docs/stt-settings)           |
| `vad`         | object | No             | Voice activity detection settings. See [VAD Settings](/docs/vad-settings) |
| `tts`         | object | No             | Text-to-speech settings. See [TTS Settings](/docs/tts-settings)           |
| `sounds`      | object | No             | Background audio settings. See [Sounds Settings](/docs/sounds-settings)   |
| `audio`       | object | No             | Input audio filtering. See [Audio Settings](/docs/audio-settings)         |

***

## Creating an Advanced Settings resource

To create Project-scoped settings, use a project-scoped API key or include `projectId` with an organization-scoped key. With an organization-scoped key, omit `projectId` to create Organization-scoped settings. Data API paths below are relative to the server URL in the [API reference](/api), which includes `/data_next`.

```http title="HTTP Request"
POST /ai/advancedSettings
Authorization: Bearer {your-api-key}
Content-Type: application/json
```
```json title="Payload"
{
  "name": "Call-centre defaults",
  "description": "Tuned for noisy call-centre environments with domain-specific vocabulary.",
  "stt": {
    "keyterms": ["Reecall", "ACME Corp"],
    "endpointing": 0.5
  },
  "vad": {
    "activationThreshold": 0.65,
    "endpointingMinDelay": 0.5,
    "endpointingMaxDelay": 3.0,
    "minSpeechDuration": 0.1,
    "disableInterruptions": false
  },
  "tts": {
    "speed": 0.25
  },
  "sounds": {
    "thinking": "keyboard"
  },
  "audio": {
    "noiseCancellation": "bvc_telephony"
  }
}
```

```json title="Response"
{
  "id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
  "name": "Call-centre defaults",
  "description": "Tuned for noisy call-centre environments with domain-specific vocabulary.",
  "stt": {
    "keyterms": ["Reecall", "ACME Corp"],
    "endpointing": 0.5
  },
  "vad": {
    "activationThreshold": 0.65,
    "endpointingMinDelay": 0.5,
    "endpointingMaxDelay": 3.0,
    "minSpeechDuration": 0.1,
    "disableInterruptions": false
  },
  "tts": {
    "speed": 0.25
  },
  "sounds": {
    "thinking": "keyboard"
  },
  "audio": {
    "noiseCancellation": "bvc_telephony"
  },
  "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2025-06-10T14:22:00.000Z",
  "updatedAt": "2025-06-10T14:22:00.000Z"
}
```

***

## Attaching to an Assistant

Link an Advanced Settings resource to an existing Assistant by setting `advancedSettingsId`:

```http title="HTTP Request"
PATCH /conversational/assistants/{your-assistant-id}
Authorization: Bearer {your-api-key}
Content-Type: application/json
```
```json title="Payload"
{
  "advancedSettingsId": "{your-advanced-settings-id}"
}
```

To detach, set the field to `null`:

```json title="Payload"
{
  "advancedSettingsId": null
}
```

***

## Updating Advanced Settings

Update the resource with PATCH. The change applies to every linked Assistant on its next conversation.

```http title="HTTP Request"
PATCH /ai/advancedSettings/{your-advanced-settings-id}
Authorization: Bearer {your-api-key}
Content-Type: application/json
```
```json title="Payload"
{
  "stt": {
    "keyterms": ["Reecall", "ACME Corp", "Support Plus"],
    "endpointing": 0.6
  }
}
```

:::info{title="When changes take effect"}

In-progress conversations continue using the settings that were active when they started.

:::

<br />

## What's next

- [STT Settings](/docs/stt-settings)
- [VAD Settings](/docs/vad-settings)
- [TTS Settings](/docs/tts-settings)
- [Sounds Settings](/docs/sounds-settings)
- [Audio Settings](/docs/audio-settings)
