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.

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 for rollout timing.

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.

configure() and configureSession() keep working during the deprecation period. Use Scheduled Deprecations if you need rollout timing and compatibility details.

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

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.

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

1. Move app-level settings to configureApp()

   Move UI, appearance, locale, and network settings out of configure() and into configureApp().

2. 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().

Before and after examples

App appearance and UI settings

Before

await api.configure({
  features: {
    interactionTitle: true,
    aiChat: false,
    documentFeedback: false,
    navigation: true,
  },
  appearance: {
    primaryColor: "#0f766e",
  },
});

After

await api.configureApp({
  ui: {
    interactionTitle: true,
    aiChat: false,
    documentFeedback: false,
    navigation: true,
  },
  appearance: {
    primaryColor: "#0f766e",
  },
});

Development-only debug panel

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

await api.configureApp({
  debug: true,
});

The debug panel is intended for development only. Keep debug disabled in staging and production.

Interface language, dictation language, and string overrides

Before

await api.configure({
  locale: {
    interfaceLanguage: "da-DK",
    dictationLanguage: "da",
    overrides: {
      "interview.document.syncDocument.label": "Sync Document",
    },
  },
});

After

await api.configureApp({
  locale: {
    interfaceLanguage: "da-DK",
    dictationLanguage: "da",
    overrides: {
      "interview.document.syncDocument.label": "Sync Document",
    },
  },
});

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.

Before

await api.configure({
  features: {
    virtualMode: true,
  },
});

await api.configureSession({
  defaultMode: "virtual",
});

After

await api.setInteractionOptions({
  mode: {
    fallback: "virtual",
    options: ["in-person", "virtual"],
  },
});

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

Before

await api.configure({
  features: {
    virtualMode: false,
  },
});

await api.configureSession({
  defaultMode: "in-person",
});

After

await api.setInteractionOptions({
  mode: {
    fallback: "in-person",
    options: ["in-person"],
  },
});

Default spoken language

Before

await api.configureSession({
  defaultLanguage: "da",
});

After

await api.setInteractionOptions({
  spokenLanguage: {
    fallback: "da",
  },
});

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".

Before

await api.configureSession({
  defaultTemplateKey: "corti-soap",
  defaultOutputLanguage: "en",
});

After

await api.setInteractionOptions({
  templates: {
    defaultTemplate: {
      behaviour: "fallback",
      template: {
        source: "standard",
        id: "corti-soap-en",
      },
    },
  },
});

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.

Document sync action

Before

await api.configure({
  features: {
    syncDocumentAction: true,
  },
});

After

await api.setInteractionOptions({
  documents: {
    actions: {
      sync: true,
    },
  },
});

Personal template editor and template management

Before

await api.configure({
  features: {
    templateEditor: true,
  },
});

After

await api.setInteractionOptions({
  templates: {
    sources: {
      personal: {
        enabled: true,
      },
    },
  },
});

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

Configuration Scenarios

See the same settings organized by implementation scenario instead of field mapping.

Scheduled Deprecations

Review timing, compatibility expectations, and rollout guidance.

API Reference

Review configureApp() and setInteractionOptions() alongside the legacy methods.