> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/settings-panel/runtime-settings-api.md).

# Runtime settings API

`IConvaiRuntimeSettingsService` is the scripting layer beneath the built-in Settings Panel. Any script can read the current settings snapshot, apply patches atomically, subscribe to change events, and control which transcript modes are exposed — without the panel being present in the scene.

Access the service through `ConvaiManager`:

```csharp
ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings);
```

### `IConvaiRuntimeSettingsService`

| Member                                                                         | Type                                         | Description                                                                                                                 |
| ------------------------------------------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Current`                                                                      | `ConvaiRuntimeSettingsSnapshot`              | Immutable snapshot of all current settings values                                                                           |
| `SupportedTranscriptModes`                                                     | `IReadOnlyCollection<ConvaiTranscriptMode>`  | Transcript modes currently registered as available for selection                                                            |
| `Changed`                                                                      | `event Action<ConvaiRuntimeSettingsChanged>` | Fired whenever any setting changes                                                                                          |
| `Apply(ConvaiRuntimeSettingsPatch patch)`                                      | `ConvaiRuntimeSettingsApplyResult`           | Apply one or more settings atomically. Fields left `null` in the patch remain unchanged                                     |
| `ResetToDefaults()`                                                            | `ConvaiRuntimeSettingsApplyResult`           | Reset all settings to project defaults                                                                                      |
| `SetSupportedTranscriptModes(IReadOnlyCollection<ConvaiTranscriptMode> modes)` | `void`                                       | Replace the set of transcript modes available for selection. Used to restrict the modes the Settings Panel dropdown exposes |

### `ConvaiRuntimeSettingsSnapshot`

An immutable struct returned by `Current` and included in apply results and change events. All fields reflect the state at the moment the snapshot was produced.

| Field                         | Type                   | Description                                             |
| ----------------------------- | ---------------------- | ------------------------------------------------------- |
| `PlayerDisplayName`           | `string`               | Current player display name shown in transcript bubbles |
| `TranscriptEnabled`           | `bool`                 | Whether transcript UI is enabled                        |
| `NotificationsEnabled`        | `bool`                 | Whether in-scene notification popups are enabled        |
| `PreferredMicrophoneDeviceId` | `string`               | Device ID of the preferred microphone input             |
| `TranscriptMode`              | `ConvaiTranscriptMode` | Current transcript display mode (`Chat` or `Subtitle`)  |

### `ConvaiRuntimeSettingsPatch`

Passed to `Apply()`. Any field left `null` remains unchanged after apply.

| Field                         | Type                    | Description                                             |
| ----------------------------- | ----------------------- | ------------------------------------------------------- |
| `PlayerDisplayName`           | `string`                | Set a new player display name. `null` = no change       |
| `TranscriptEnabled`           | `bool?`                 | Enable or disable the transcript UI. `null` = no change |
| `NotificationsEnabled`        | `bool?`                 | Enable or disable notifications. `null` = no change     |
| `PreferredMicrophoneDeviceId` | `string`                | Set preferred microphone device ID. `null` = no change  |
| `TranscriptMode`              | `ConvaiTranscriptMode?` | Switch transcript display mode. `null` = no change      |

### `ConvaiRuntimeSettingsApplyResult`

Returned by `Apply()` and `ResetToDefaults()`.

| Field               | Type                              | Description                                                  |
| ------------------- | --------------------------------- | ------------------------------------------------------------ |
| `Success`           | `bool`                            | `true` if the apply operation succeeded                      |
| `Snapshot`          | `ConvaiRuntimeSettingsSnapshot`   | Resulting settings state after the apply                     |
| `AppliedMask`       | `ConvaiRuntimeSettingsChangeMask` | Bitmask of which fields actually changed                     |
| `ValidationMessage` | `string`                          | Reason for failure when `Success == false`. Empty on success |

### `ConvaiRuntimeSettingsChanged`

The payload delivered to `Changed` subscribers.

| Field      | Type                              | Description                             |
| ---------- | --------------------------------- | --------------------------------------- |
| `Previous` | `ConvaiRuntimeSettingsSnapshot`   | Settings state before the change        |
| `Current`  | `ConvaiRuntimeSettingsSnapshot`   | Settings state after the change         |
| `Mask`     | `ConvaiRuntimeSettingsChangeMask` | Bitmask indicating which fields changed |

### `ConvaiRuntimeSettingsChangeMask`

A `[Flags]` enum used in `AppliedMask` and `ConvaiRuntimeSettingsChanged.Mask`. Compare with bitwise AND to detect specific changes.

| Value                         | Description                         |
| ----------------------------- | ----------------------------------- |
| `None`                        | No fields changed                   |
| `PlayerDisplayName`           | Player display name changed         |
| `TranscriptEnabled`           | Transcript enabled state changed    |
| `NotificationsEnabled`        | Notifications enabled state changed |
| `PreferredMicrophoneDeviceId` | Microphone selection changed        |
| `TranscriptMode`              | Transcript mode changed             |
| `All`                         | All fields                          |

### Transcript mode limitation in the panel

The **Transcript Style** dropdown in the Settings Panel exposes only the modes registered in `SupportedTranscriptModes`. By default, `SettingsPanelPresenter` initializes this to `{ ConvaiTranscriptMode.Chat }` only.

To expose additional modes in the panel dropdown, call `SetSupportedTranscriptModes()` before the panel opens:

```csharp
if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
{
    settings.SetSupportedTranscriptModes(new[]
    {
        ConvaiTranscriptMode.Chat,
        ConvaiTranscriptMode.Subtitle
    });
}
```

To switch to Subtitle mode bypassing the panel entirely, use `Apply()` directly:

```csharp
settings.Apply(new ConvaiRuntimeSettingsPatch
{
    TranscriptMode = ConvaiTranscriptMode.Subtitle
});
```

See [Chat and subtitle modes](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md) for full mode-switching details.

### Usage examples

#### Read current settings

```csharp
using Convai.Runtime.Components;
using Convai.Shared.Types;
using UnityEngine;

public class SettingsReader : MonoBehaviour
{
    private void Start()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
        {
            ConvaiRuntimeSettingsSnapshot current = settings.Current;
            Debug.Log($"Player name: {current.PlayerDisplayName}");
            Debug.Log($"Transcript on: {current.TranscriptEnabled}");
            Debug.Log($"Mode: {current.TranscriptMode}");
        }
    }
}
```

#### Apply a settings patch

```csharp
if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
{
    var result = settings.Apply(new ConvaiRuntimeSettingsPatch
    {
        PlayerDisplayName = "Dr. Kaan",
        TranscriptEnabled = true,
        TranscriptMode = ConvaiTranscriptMode.Subtitle
    });

    if (!result.Success)
        Debug.LogWarning($"Settings apply failed: {result.ValidationMessage}");
}
```

#### React to settings changes

```csharp
using Convai.Runtime.Components;
using Convai.Shared.Abstractions;
using Convai.Shared.Types;
using UnityEngine;

public class SettingsChangeReactor : MonoBehaviour
{
    private IConvaiRuntimeSettingsService _settings;

    private void OnEnable()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out _settings))
            _settings.Changed += OnSettingsChanged;
    }

    private void OnDisable()
    {
        if (_settings != null)
            _settings.Changed -= OnSettingsChanged;
    }

    private void OnSettingsChanged(ConvaiRuntimeSettingsChanged changed)
    {
        if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PreferredMicrophoneDeviceId) != 0)
        {
            Debug.Log($"Microphone changed to: {changed.Current.PreferredMicrophoneDeviceId}");
            ApplyMicrophoneChange(changed.Current.PreferredMicrophoneDeviceId);
        }

        if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PlayerDisplayName) != 0)
        {
            UpdatePlayerNameDisplay(changed.Current.PlayerDisplayName);
        }
    }
}
```

#### Analytics — track settings changes

A training platform logs when trainees change their microphone device for session quality analysis:

```csharp
private void OnSettingsChanged(ConvaiRuntimeSettingsChanged changed)
{
    if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PreferredMicrophoneDeviceId) != 0)
    {
        AnalyticsTracker.LogEvent("microphone_changed", new Dictionary<string, object>
        {
            { "previous", changed.Previous.PreferredMicrophoneDeviceId },
            { "current", changed.Current.PreferredMicrophoneDeviceId }
        });
    }
}
```

### Troubleshooting

| Symptom                                | Likely cause                                         | Fix                                                                                                                   |
| -------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Apply()` returns `Success == false`   | Validation failure                                   | Check `result.ValidationMessage` for the reason                                                                       |
| `Changed` event not firing             | Not subscribed, or subscribed after settings changed | Subscribe in `OnEnable` before the session starts                                                                     |
| `ResetToDefaults()` result not checked | Return value ignored                                 | `ResetToDefaults()` returns `ConvaiRuntimeSettingsApplyResult` — check `result.Success` if the reset must be verified |

### Next steps

{% content-ref url="/pages/1e28d73ef0dad9569b5d54c8f9f0b70586425f5a" %}
[Settings panel](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/settings-panel.md)
{% endcontent-ref %}

{% content-ref url="/pages/04dba1e30bd200179a770ba5dffcaab5b5eadf16" %}
[Chat and subtitle modes](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/settings-panel/runtime-settings-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.