> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Config Migration Guide

> Move from configure() and configureSession() to configureApp() and setInteractionOptions().

Use this guide to move an existing Embedded API integration from the legacy configuration structure to the new split between app-level configuration and interaction options.

<Warning>
  Due by 2026-11-29. `configure()` and `configureSession()` remain supported
  until then, but new integrations should move to `configureApp()` and
  `setInteractionOptions()` now. See [Scheduled
  Deprecations](/assistant/deprecation-timeline) for rollout timing.
</Warning>

## Overview

The new configuration structure separates two responsibilities:

* `configureApp()` is for app-level configuration such as UI settings, appearance, locale, and network settings. It is patchable and you may call it multiple times.
* `setInteractionOptions()` is for interaction or session-level configuration such as mode, spoken language, template defaults, and document actions. Set it before the user starts or opens an interaction.

<Info>
  `configure()` and `configureSession()` keep working during the deprecation
  period. Use [Scheduled Deprecations](/assistant/deprecation-timeline) if you
  need rollout timing and compatibility details.
</Info>

## Reference

### Mapping from `configure()`

The second column shows the request shape to use in the new method call, not a response path.

| Current field                 | Use in                                                                              | Notes                                                                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `features.interactionTitle`   | `configureApp({ ui: { interactionTitle: ... } })`                                   | App-level UI setting                                                                                                                       |
| `features.aiChat`             | `configureApp({ ui: { aiChat: ... } })`                                             | App-level UI setting                                                                                                                       |
| `features.documentFeedback`   | `configureApp({ ui: { documentFeedback: ... } })`                                   | App-level UI setting                                                                                                                       |
| `features.navigation`         | `configureApp({ ui: { navigation: ... } })`                                         | App-level UI setting                                                                                                                       |
| `features.virtualMode`        | `setInteractionOptions({ mode: { options: [...] } })`                               | Use `options: ["in-person", "virtual"]` when virtual mode should be available, or `options: ["in-person"]` when it should not be available |
| `features.syncDocumentAction` | `setInteractionOptions({ documents: { actions: { sync: ... } } })`                  | Interaction-level document action                                                                                                          |
| `features.templateEditor`     | `setInteractionOptions({ templates: { sources: { personal: { enabled: ... } } } })` | Keeps the existing personal template capability                                                                                            |
| `appearance.primaryColor`     | `configureApp({ appearance: { primaryColor: ... } })`                               | App branding                                                                                                                               |
| `locale.interfaceLanguage`    | `configureApp({ locale: { interfaceLanguage: ... } })`                              | UI language                                                                                                                                |
| `locale.dictationLanguage`    | `configureApp({ locale: { dictationLanguage: ... } })`                              | Default dictation language                                                                                                                 |
| `locale.overrides`            | `configureApp({ locale: { overrides: ... } })`                                      | String overrides                                                                                                                           |
| `network.websocketBaseUrl`    | `configureApp({ network: { websocketBaseUrl: ... } })`                              | Proxy-only WebSocket endpoint override                                                                                                     |

<Info>
  `configureApp({ debug: true })` enables a debug panel for development.
  There is no legacy `configure()` equivalent for this setting, and you should
  not enable it in staging or production.
</Info>

### Mapping from `configureSession()`

| Current field           | Use in                                                           | Notes                                                                                                               |
| ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `defaultMode`           | `setInteractionOptions({ mode: { fallback: ... } })`             | Pair this with `mode.options` to decide which modes are available                                                   |
| `defaultLanguage`       | `setInteractionOptions({ spokenLanguage: { fallback: ... } })`   | Interaction-level spoken language fallback                                                                          |
| `defaultTemplateKey`    | `setInteractionOptions({ templates: { defaultTemplate: ... } })` | Use `source: "standard"`, `behaviour: "fallback"`, and the fully resolved template id                               |
| `defaultOutputLanguage` | `templates.defaultTemplate.template.id`                          | Compose the new template id from the old key plus language, for example `corti-soap` + `en` becomes `corti-soap-en` |

## Migration path

<Steps>
  <Step title="Move app-level settings to configureApp()">
    Move UI, appearance, locale, and network settings out of `configure()` and into `configureApp()`.
  </Step>

  <Step title="Move interaction defaults to setInteractionOptions()">
    Move mode, spoken language, template defaults, document sync, and personal
    template availability out of `configure()` or `configureSession()` and into
    `setInteractionOptions()`.
  </Step>
</Steps>

## Before and after examples

### App appearance and UI settings

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      features: {
        interactionTitle: true,
        aiChat: false,
        documentFeedback: false,
        navigation: true,
      },
      appearance: {
        primaryColor: "#0f766e",
      },
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.configureApp({
      ui: {
        interactionTitle: true,
        aiChat: false,
        documentFeedback: false,
        navigation: true,
      },
      appearance: {
        primaryColor: "#0f766e",
      },
    });
    ```
  </div>
</Columns>

### Development-only debug panel

Use `debug` when you need the embedded Assistant debug panel during local
development or troubleshooting.

```javascript theme={null}
await api.configureApp({
  debug: true,
});
```

<Warning>
  The debug panel is intended for development only. Keep `debug` disabled in
  staging and production.
</Warning>

### Interface language, dictation language, and string overrides

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      locale: {
        interfaceLanguage: "da-DK",
        dictationLanguage: "da",
        overrides: {
          "interview.document.syncDocument.label": "Sync Document",
        },
      },
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.configureApp({
      locale: {
        interfaceLanguage: "da-DK",
        dictationLanguage: "da",
        overrides: {
          "interview.document.syncDocument.label": "Sync Document",
        },
      },
    });
    ```
  </div>
</Columns>

### Default mode and virtual mode

Use `mode.options` to replace `features.virtualMode` and `mode.fallback` to replace `defaultMode`.

When `virtualMode` is `false`, the key migration step is to remove `"virtual"` from `mode.options`.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      features: {
        virtualMode: true,
      },
    });

    await api.configureSession({
      defaultMode: "virtual",
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      mode: {
        fallback: "virtual",
        options: ["in-person", "virtual"],
      },
    });
    ```
  </div>
</Columns>

For the more interesting non-default case where virtual mode should not be available:

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      features: {
        virtualMode: false,
      },
    });

    await api.configureSession({
      defaultMode: "in-person",
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      mode: {
        fallback: "in-person",
        options: ["in-person"],
      },
    });
    ```
  </div>
</Columns>

### Default spoken language

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configureSession({
      defaultLanguage: "da",
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      spokenLanguage: {
        fallback: "da",
      },
    });
    ```
  </div>
</Columns>

### Default template

This remains fallback behavior, just like before. Map `defaultTemplateKey` to a standard template source and pass the fully resolved template id.

In the new API, pass the fully resolved template id. If the old configuration used `defaultTemplateKey: "corti-soap"` together with `defaultOutputLanguage: "en"`, the new `template.id` should be `"corti-soap-en"`.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configureSession({
      defaultTemplateKey: "corti-soap",
      defaultOutputLanguage: "en",
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      templates: {
        defaultTemplate: {
          behaviour: "fallback",
          template: {
            source: "standard",
            id: "corti-soap-en",
          },
        },
      },
    });
    ```
  </div>
</Columns>

<Note>
  The old configuration resolved the selected template from the pair
  `defaultTemplateKey` plus `defaultOutputLanguage`. In the new API, you must
  pass the already resolved template id directly, for example `corti-soap-en`.
</Note>

### Document sync action

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      features: {
        syncDocumentAction: true,
      },
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      documents: {
        actions: {
          sync: true,
        },
      },
    });
    ```
  </div>
</Columns>

### Personal template editor and template management

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    await api.configure({
      features: {
        templateEditor: true,
      },
    });
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    await api.setInteractionOptions({
      templates: {
        sources: {
          personal: {
            enabled: true,
          },
        },
      },
    });
    ```
  </div>
</Columns>

## Timeline

* **Current**: `configure()` and `configureSession()` still work during the deprecation period
* **Future**: Legacy configuration support ends on 2026-11-29
* **Action required**: Move to `configureApp()` and `setInteractionOptions()` before the deadline

## Related pages

<CardGroup cols={2}>
  <Card title="Configuration Scenarios" icon="sliders-horizontal" href="/assistant/configuration-scenarios">
    See the same settings organized by implementation scenario instead of field mapping.
  </Card>

  <Card title="Scheduled Deprecations" icon="clock-3" href="/assistant/deprecation-timeline">
    Review timing, compatibility expectations, and rollout guidance.
  </Card>

  <Card title="API Reference" icon="book" href="/assistant/api-reference">
    Review `configureApp()` and `setInteractionOptions()` alongside the legacy methods.
  </Card>
</CardGroup>