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

# 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](#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](/assistant/configuration-migration). For timelines and compatibility, see [Scheduled Deprecations](/assistant/deprecation-timeline).

## App UI and navigation

<a id="i-want-to-hide-the-interaction-title" />

<Accordion title="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.

  ```javascript theme={null}
  await api.configureApp({
    ui: {
      interactionTitle: false,
    },
  });
  ```
</Accordion>

<a id="i-want-to-disable-document-feedback" />

<Accordion title="I want to disable document feedback">
  Use this when you do not want clinicians to submit document feedback from inside the embedded assistant.

  ```javascript theme={null}
  await api.configureApp({
    ui: {
      documentFeedback: false,
    },
  });
  ```
</Accordion>

<a id="i-want-to-remove-ai-chat-from-the-embedded-assistant" />

<Accordion title="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.

  ```javascript theme={null}
  await api.configureApp({
    ui: {
      aiChat: false,
    },
  });
  ```
</Accordion>

<a id="i-want-to-keep-users-inside-the-current-interaction" />

<Accordion title="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.

  ```javascript theme={null}
  await api.configureApp({
    ui: {
      navigation: false,
    },
  });
  ```
</Accordion>

<a id="i-want-to-enable-the-debug-panel-during-development" />

<Accordion title="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.

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

  <Warning>
    `debug` is only intended for development. Do not enable it in staging or
    production.
  </Warning>
</Accordion>

<a id="i-want-a-focused-embedded-ui-with-only-the-core-workflow-visible" />

<Accordion title="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.

  ```javascript theme={null}
  await api.configureApp({
    ui: {
      interactionTitle: false,
      aiChat: false,
      documentFeedback: false,
      navigation: false,
    },
  });
  ```
</Accordion>

## Appearance, language, and network

<a id="i-want-to-change-the-primary-accent-color" />

<Accordion title="I want to change the primary accent color">
  Use this when you want the embedded experience to match your product branding.

  <Warning>
    Always ensure WCAG 2.2 AA conformance when customizing appearance
  </Warning>

  ```javascript theme={null}
  await api.configureApp({
    appearance: {
      primaryColor: "#0f766e",
    },
  });
  ```
</Accordion>

<a id="i-want-to-set-the-current-interface-language" />

<Accordion title="I want to set the current interface language">
  Use this when you want to control the language of the embedded UI.

  ```javascript theme={null}
  await api.configureApp({
    locale: {
      interfaceLanguage: "da-DK",
    },
  });
  ```
</Accordion>

<a id="i-want-new-sessions-to-start-with-a-specific-dictation-language" />

<Accordion title="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.

  ```javascript theme={null}
  await api.configureApp({
    locale: {
      dictationLanguage: "da",
    },
  });
  ```
</Accordion>

<a id="i-want-to-override-specific-interface-text" />

<Accordion title="I want to override specific interface text">
  Use this when you need to replace specific interface strings with product-specific wording.

  ```javascript theme={null}
  await api.configureApp({
    locale: {
      overrides: {
        "interview.document.syncDocument.label": "Sync Document",
      },
    },
  });
  ```
</Accordion>

<a id="i-want-the-embedded-assistant-to-use-a-custom-websocket-endpoint" />

<Accordion title="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](/assistant/proxy).

  ```javascript theme={null}
  await api.configureApp({
    network: {
      websocketBaseUrl: "wss://proxy.example.com",
    },
  });
  ```
</Accordion>

## Interaction mode and spoken language

<a id="i-want-sessions-to-default-to-in-person-mode" />

<Accordion title="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.

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

<a id="i-want-to-allow-both-in-person-and-virtual-modes-while-setting-a-fallback" />

<Accordion title="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.

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

<a id="i-want-to-lock-the-embedded-instance-to-only-virtual-mode-or-only-in-person-mode" />

<Accordion title="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.

  <CodeGroup>
    ```javascript Virtual only theme={null}
    await api.setInteractionOptions({
      mode: {
        fallback: "virtual",
        options: ["virtual"],
      },
    });
    ```

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

<a id="i-want-sessions-to-start-with-a-specific-spoken-language" />

<Accordion title="I want sessions to start with a specific spoken language">
  Use this when a session should default to a specific spoken language.

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

<a id="i-want-to-restrict-spoken-language-options" />

<Accordion title="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`.

  <CodeGroup>
    ```javascript Multiple spoken languages theme={null}
    // 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,
      },
    });
    ```

    ```javascript Single spoken language theme={null}
    // Replace this with your value
    const SPOKEN_LANGUAGE = "da";

    await api.setInteractionOptions({
      spokenLanguage: {
        fallback: SPOKEN_LANGUAGE,
        options: [SPOKEN_LANGUAGE],
      },
    });
    ```
  </CodeGroup>
</Accordion>

## Template defaults and personal templates

<a id="i-want-new-sessions-to-fall-back-to-a-default-template" />

<Accordion title="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.

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

  <Note>
    If your old integration used `defaultTemplateKey: "corti-soap"` together with
    `defaultOutputLanguage: "en"`, the new `template.id` should be
    `"corti-soap-en"`.
  </Note>
</Accordion>

<a id="i-want-to-prevent-clinicians-from-changing-their-default-template" />

<Accordion title="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.

  ```javascript theme={null}
  // 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,
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-clinicians-to-be-able-to-use-personal-templates" />

<Accordion title="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.

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

<a id="i-want-to-control-which-fields-are-available-in-the-personal-template-editor" />

<Accordion title="I want to control which fields are available in the personal template editor">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0). Only applies to new templates.</Note>

  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 misc prompt:

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        personal: {
          enabled: true,
          sectionFields: {
            heading: { editable: true },
            description: { editable: false },
            miscPrompt: { visible: false },
          },
        },
      },
    },
  });
  ```

  <Note>
    `heading` and `description` are always visible; only `editable` applies.
    For `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`.
  </Note>
</Accordion>

## Standard and project template sources

<a id="i-want-to-show-all-standard-templates" />

<Accordion title="I want to show all standard templates">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

  Use this when standard templates should remain available without filtering.

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

<a id="i-want-to-disable-standard-templates-entirely" />

<Accordion title="I want to disable standard templates entirely">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        standard: {
          enabled: false,
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-show-only-standard-templates-for-one-or-more-regions" />

<Accordion title="I want to show only standard templates for one or more regions">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

  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.

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        standard: {
          enabled: true,
          include: {
            regions: ["BEL"],
          },
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-show-only-standard-templates-for-one-or-more-template-families" />

<Accordion title="I want to show only standard templates for one or more template families">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        standard: {
          enabled: true,
          include: {
            families: ["soap"],
          },
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-exclude-standard-templates-from-one-or-more-regions" />

<Accordion title="I want to exclude standard templates from one or more regions">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        standard: {
          enabled: true,
          exclude: {
            regions: ["USA"],
          },
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-exclude-standard-templates-from-one-or-more-families" />

<Accordion title="I want to exclude standard templates from one or more families">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        standard: {
          enabled: true,
          exclude: {
            families: ["letter"],
          },
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-combine-include-and-exclude-for-standard-templates" />

<Accordion title="I want to combine include and exclude for standard templates">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

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

  <Note>
    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.
  </Note>
</Accordion>

<a id="i-want-to-show-only-selected-project-templates" />

<Accordion title="I want to show only selected project templates">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

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

<a id="i-want-to-exclude-specific-project-templates" />

<Accordion title="I want to exclude specific project templates">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        project: {
          enabled: true,
          exclude: {
            ids: ["<project-template-uuid-1>"],
          },
        },
      },
    },
  });
  ```
</Accordion>

<a id="i-want-to-disable-project-templates-entirely" />

<Accordion title="I want to disable project templates entirely">
  <Note>Requires [Guided Document Generation](/release-notes/corti-assistant#v12-19-0).</Note>

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

  ```javascript theme={null}
  await api.setInteractionOptions({
    templates: {
      sources: {
        project: {
          enabled: false,
        },
      },
    },
  });
  ```
</Accordion>

## Documents and companion workflows

<a id="i-want-to-show-the-document-sync-action" />

<Accordion title="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.

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

<a id="i-want-to-limit-the-number-of-generated-documents" />

<Accordion title="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.

  <CodeGroup>
    ```javascript One generated document theme={null}
    const MAX_GENERATED_DOCUMENTS = 1;

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

    ```javascript Two generated documents theme={null}
    const MAX_GENERATED_DOCUMENTS = 2;

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

    ```javascript Unlimited documents theme={null}
    const MAX_GENERATED_DOCUMENTS = "unlimited";

    await api.setInteractionOptions({
      documents: {
        maxGenerated: MAX_GENERATED_DOCUMENTS,
      },
    });
    ```
  </CodeGroup>
</Accordion>

<a id="i-want-to-limit-which-document-output-languages-are-available" />

<Accordion title="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](/release-notes/corti-assistant#v12-19-0), 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.

  ```javascript theme={null}
  await api.setInteractionOptions({
    documents: {
      allowedLanguages: ["en", "da"],
    },
  });
  ```
</Accordion>

<a id="i-want-clinicians-to-pair-the-corti-mobile-companion-app" />

<Accordion title="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.

  ```typescript theme={null}
  // 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()`](/assistant/api/show-device-link-qr) for return statuses and error handling.
</Accordion>

## Combined setup flows

<a id="i-need-to-configure-several-settings-together" />

<Accordion title="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.

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

  ```javascript theme={null}
  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.

  ```javascript theme={null}
  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,
      },
    },
  });
  ```

  <Tip>
    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.
  </Tip>
</Accordion>

## Related pages

<CardGroup cols={2}>
  <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 method-level details for `configureApp()` and `setInteractionOptions()`.
  </Card>
</CardGroup>