Embedded API Configuration Scenarios

Scenario-based examples for configureApp() and setInteractionOptions().

Use this page when you want practical examples for the current Embedded API configuration options. If you need to combine branding, UI, and interaction defaults in one setup flow, jump to I need to configure several settings together.

Intended usage pattern

• Call configureApp() for app-level settings.
• Call setInteractionOptions() before the user starts or opens an interaction.

If you are moving from configure() or configureSession(), use the Config Migration Guide. For timelines and compatibility, see Scheduled Deprecations.

App UI and navigation

I want to hide the interaction title

Use this when the interaction title is already shown elsewhere in your product and you do not want to repeat it inside the embedded assistant.

await api.configureApp({
  ui: {
    interactionTitle: false,
  },
});

I want to disable document feedback

Use this when you do not want clinicians to submit document feedback from inside the embedded assistant.

await api.configureApp({
  ui: {
    documentFeedback: false,
  },
});

I want to remove AI chat from the embedded assistant

Use this when your workflow does not allow in-product AI chat or when you want to keep the embedded experience focused on recording and documentation only.

await api.configureApp({
  ui: {
    aiChat: false,
  },
});

I want to keep users inside the current interaction

Use this when you do not want clinicians to open settings, browse older interactions, or navigate away from the flow controlled by your host application.

await api.configureApp({
  ui: {
    navigation: false,
  },
});

I want to enable the debug panel during development

Use this when you need the embedded Assistant debug panel while developing or troubleshooting an integration locally.

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

debug is only intended for development. Do not enable it in staging or production.

I want a focused embedded UI with only the core workflow visible

Use this when your product already provides the surrounding navigation and context, and you want the embedded assistant to stay limited to the current interaction.

await api.configureApp({
  ui: {
    interactionTitle: false,
    aiChat: false,
    documentFeedback: false,
    navigation: false,
  },
});

Appearance, language, and network

I want to change the primary accent color

Use this when you want the embedded experience to match your product branding.

Always ensure WCAG 2.2 AA conformance when customizing appearance

await api.configureApp({
  appearance: {
    primaryColor: "#0f766e",
  },
});

I want to set the current interface language

Use this when you want to control the language of the embedded UI.

await api.configureApp({
  locale: {
    interfaceLanguage: "da-DK",
  },
});

I want new sessions to start with a specific dictation language

Use this when you want the embedded experience to start with a specific dictation language.

await api.configureApp({
  locale: {
    dictationLanguage: "da",
  },
});

I want to override specific interface text

Use this when you need to replace specific interface strings with product-specific wording.

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

I want the embedded assistant to use a custom WebSocket endpoint

Use this only for proxy setups that need a custom WebSocket endpoint. See the Proxy guide.

await api.configureApp({
  network: {
    websocketBaseUrl: "wss://proxy.example.com",
  },
});

Interaction mode and spoken language

I want sessions to default to in-person mode

Use this when you want to set the initial interaction mode while keeping both modes available.

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

I want to allow both in-person and virtual modes while setting a fallback

Use this when users should still be able to switch modes, but one mode should be the default.

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

I want to lock the embedded instance to only virtual mode or only in-person mode

Use this when your workflow only supports one interaction type.

Virtual only

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

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

I want sessions to start with a specific spoken language

Use this when a session should default to a specific spoken language.

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

I want to restrict spoken language options

Use this when an embedded deployment supports only a specific set of spoken languages. If you provide one option, users cannot change the spoken language. If you provide a fallback, make sure it is included in options.

Multiple spoken languages

// Replace these with your values
const FALLBACK_LANGUAGE = "da";
const SPOKEN_LANGUAGE_OPTIONS = ["da", "en"];

await api.setInteractionOptions({
  spokenLanguage: {
    fallback: FALLBACK_LANGUAGE,
    options: SPOKEN_LANGUAGE_OPTIONS,
  },
});

// Replace this with your value
const SPOKEN_LANGUAGE = "da";

await api.setInteractionOptions({
  spokenLanguage: {
    fallback: SPOKEN_LANGUAGE,
    options: [SPOKEN_LANGUAGE],
  },
});

Template defaults and personal templates

I want new sessions to fall back to a default template

Use this when you want to provide a fallback standard template for new sessions using the fully resolved template id. It is used only when the user does not already have their own default template set.

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

If your old integration used defaultTemplateKey: "corti-soap" together with defaultOutputLanguage: "en", the new template.id should be "corti-soap-en".

I want to prevent clinicians from changing their default template

Use this when your host application controls the default template and clinicians should not be able to choose or persist their own default from inside the embedded Assistant.

// Replace this with your value
const DEFAULT_TEMPLATE_ID = "corti-soap-en";

await api.setInteractionOptions({
  templates: {
    defaultTemplate: {
      allowUserSelection: false,
      behaviour: "fallback",
      template: {
        source: "standard",
        id: DEFAULT_TEMPLATE_ID,
      },
    },
  },
});

I want clinicians to be able to use personal templates

Use this when you want clinicians to create, edit, copy, view, or delete personal templates through the Guided Document Generation template editor.

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

I want to control which fields are available in the personal template editor

Requires Guided Document Generation. Only applies to new templates.

Use this when you want to hide or lock specific section-level fields in the guided template creation flow. For example, to let users edit headings but hide the writing-style and misc prompts:

await api.setInteractionOptions({
  templates: {
    sources: {
      personal: {
        enabled: true,
        sectionFields: {
          heading: { editable: true },
          description: { editable: false },
          contentPrompt: { visible: true, editable: false },
          writingStylePrompt: { visible: false },
          miscPrompt: { visible: false },
        },
      },
    },
  },
});

heading and description are always visible; only editable applies. For contentPrompt, writingStylePrompt, miscPrompt, and outputSchema, omitting visible or setting visible: false hides the field and prevents editing. When a prompt field is visible, it is editable by default unless you set editable: false.

Standard and project template sources

I want to show all standard templates

Requires Guided Document Generation.

Use this when standard templates should remain available without filtering.

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

I want to disable standard templates entirely

Requires Guided Document Generation.

Use this when the embedded assistant should not show any standard templates in the picker.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: false,
      },
    },
  },
});

I want to show only standard templates for one or more regions

Requires Guided Document Generation.

Use this when the embedded experience should only present standard templates from specific regions using ISO 3166-1 alpha-3 codes such as BEL, DNK, or CAN. When limited to a single region, the region headline is automatically hidden.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: true,
        include: {
          regions: ["BEL"],
        },
      },
    },
  },
});

I want to show only standard templates for one or more template families

Requires Guided Document Generation.

Use this when you want to narrow standard templates by family, such as soap.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: true,
        include: {
          families: ["soap"],
        },
      },
    },
  },
});

I want to exclude standard templates from one or more regions

Requires Guided Document Generation.

Use this when standard templates should stay available, but specific regions should be removed from the picker.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: true,
        exclude: {
          regions: ["USA"],
        },
      },
    },
  },
});

I want to exclude standard templates from one or more families

Requires Guided Document Generation.

Use this when you want to remove a family such as letter while keeping other standard templates available.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: true,
        exclude: {
          families: ["letter"],
        },
      },
    },
  },
});

I want to combine include and exclude for standard templates

Requires Guided Document Generation.

Use this when you need both narrowing and removal in the same configuration. The embedded assistant applies include first and exclude second.

await api.setInteractionOptions({
  templates: {
    sources: {
      standard: {
        enabled: true,
        include: {
          regions: ["BEL", "DNK"],
          families: ["soap", "letter"],
        },
        exclude: {
          regions: ["DNK"],
          families: ["letter"],
        },
      },
    },
  },
});

Region values use ISO 3166-1 alpha-3 codes such as BEL, DNK, or CAN. Family values are standard template family identifiers such as soap, depending on the available standard template metadata.

I want to show only selected project templates

Requires Guided Document Generation.

Use this when you want to expose project templates selectively. Project templates are referenced by UUID in include.ids and exclude.ids.

await api.setInteractionOptions({
  templates: {
    sources: {
      project: {
        enabled: true,
        include: {
          ids: ["<project-template-uuid-1>", "<project-template-uuid-2>"],
        },
      },
    },
  },
});

I want to exclude specific project templates

Requires Guided Document Generation.

Use this when project templates should remain available, but a specific UUID or set of UUIDs must be hidden.

await api.setInteractionOptions({
  templates: {
    sources: {
      project: {
        enabled: true,
        exclude: {
          ids: ["<project-template-uuid-1>"],
        },
      },
    },
  },
});

I want to disable project templates entirely

Requires Guided Document Generation.

Use this when the embedded assistant should not show any project templates in the picker.

await api.setInteractionOptions({
  templates: {
    sources: {
      project: {
        enabled: false,
      },
    },
  },
});

Documents and companion workflows

I want to show the document sync action

Use this when you want to show or hide the document sync action inside the embedded experience.

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

I want to limit the number of generated documents

Use this when an embedded workflow should allow only one or two generated documents for the current interaction. When the limit is reached, document generation controls are hidden.

One generated document

const MAX_GENERATED_DOCUMENTS = 1;

await api.setInteractionOptions({
  documents: {
    maxGenerated: MAX_GENERATED_DOCUMENTS,
  },
});

const MAX_GENERATED_DOCUMENTS = 2;

await api.setInteractionOptions({
  documents: {
    maxGenerated: MAX_GENERATED_DOCUMENTS,
  },
});

const MAX_GENERATED_DOCUMENTS = "unlimited";

await api.setInteractionOptions({
  documents: {
    maxGenerated: MAX_GENERATED_DOCUMENTS,
  },
});

I want to limit which document output languages are available

Use this when you want to restrict the output language options shown to users. For Guided Document Generation, the output language dropdown displays only the allowed languages; if restricted to a single language, the dropdown is disabled. For older document generation, this limits which template language groups appear in the left sidebar.

await api.setInteractionOptions({
  documents: {
    allowedLanguages: ["en", "da"],
  },
});

I want clinicians to pair the Corti mobile companion app

Use this when your embedded deployment offers phone-based companion capture. Enable the companion app surface at app level, then call showDeviceLinkQR() with the current user’s OAuth token response when the user starts pairing.

// Replace these with your values
const ACCESS_TOKEN = "<your-access-token>";
const REFRESH_TOKEN = "<your-refresh-token>";

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

const result = await api.showDeviceLinkQR({
  access_token: ACCESS_TOKEN,
  refresh_token: REFRESH_TOKEN,
  token_type: "Bearer",
});

if (result.status === "approved") {
  // The mobile companion app was paired successfully.
}

See showDeviceLinkQR() for return statuses and error handling.

Combined setup flows

I need to configure several settings together

Use this when you need to apply several settings together.

If the settings all belong to configureApp(), you can group them into one call or chain multiple configureApp() calls. Because configureApp() is patchable, both patterns are valid.

await api.configureApp({
  ui: {
    interactionTitle: true,
    aiChat: false,
    navigation: false,
  },
  appearance: {
    primaryColor: "#0f766e",
  },
  locale: {
    interfaceLanguage: "da-DK",
    dictationLanguage: "da",
  },
});

await api.configureApp({
  ui: {
    interactionTitle: true,
    aiChat: false,
  },
});

await api.configureApp({
  appearance: {
    primaryColor: "#0f766e",
  },
});

await api.configureApp({
  locale: {
    interfaceLanguage: "da-DK",
    dictationLanguage: "da",
  },
});

If you need both app-level settings and interaction-level settings, group app-level settings inside configureApp() as needed, then call setInteractionOptions() before the user starts or opens an interaction.

await api.configureApp({
  ui: {
    navigation: false,
    documentFeedback: false,
  },
  locale: {
    interfaceLanguage: "da-DK",
  },
});

await api.setInteractionOptions({
  mode: {
    fallback: "virtual",
    options: ["in-person", "virtual"],
  },
  spokenLanguage: {
    fallback: "da",
  },
  documents: {
    actions: {
      sync: true,
    },
  },
});

A practical rule is: optional app-level settings can be grouped or split across configureApp() calls, but interaction options should be finalized in setInteractionOptions() before the interaction is opened.

Related pages

Scheduled Deprecations

Review timing, compatibility expectations, and rollout guidance.

API Reference

Review method-level details for configureApp() and setInteractionOptions().