setInteractionOptions()

Use setInteractionOptions() for interaction-level defaults such as mode, spoken language, template defaults, personal templates, standard templates, project templates, inline templates, template editor sections, and document actions. When you set templates.defaultTemplate, it can provide a fallback template for new sessions or force the first generated document to use a specific template. Fallback templates are used only when the user does not already have their own default template set.

Applies to Web Component, Window API, and PostMessage. Examples on this page use the Web Component API shape.

Set interaction options before the user starts or opens an interaction.

Use Configuration Scenarios for practical examples and Supported Values for supported languages and other lookup values.

For accounts still using legacy templates, templates.sources.standard, templates.sources.project, and templates.sources.inline are inert. Corti Assistant dispatches embedded.interactionOptionsWarning with unsupportedSources. These options apply to Guided Document Generation, the default template system.

Usage

await api.setInteractionOptions({
  mode: {
    fallback: "in-person",
    options: ["in-person", "virtual"],
  },
  spokenLanguage: {
    fallback: "da",
    options: ["da", "en"],
  },
  templates: {
    sources: {
      personal: {
        enabled: true,
        sectionFields: {
          heading: { editable: true },
          description: { editable: true },
          miscPrompt: { visible: true, editable: true },
          outputSchema: { visible: true, editable: true },
        },
      },
      standard: {
        enabled: true,
        include: {
          regions: ["BEL"],
          families: ["soap"],
        },
        exclude: {
          regions: ["USA"],
          families: ["letter"],
        },
      },
      project: {
        enabled: true,
        include: {
          ids: ["7a0ab5b8-1f62-4f75-86a7-4fcd8fd07b5d"],
        },
        exclude: {
          ids: ["d7a7fd8c-8892-4475-81d3-3414b7d8e27d"],
        },
      },
      inline: {
        enabled: true,
        templates: [
          {
            id: "inline-soap",
            name: "Embedded SOAP",
            generation: {
              instructions: {
                prompt: "Generate a concise SOAP note for the current encounter.",
              },
              sections: [
                {
                  heading: "Subjective",
                  instructions: {
                    contentPrompt: "Summarize the patient's subjective symptoms.",
                  },
                },
              ],
            },
          },
        ],
      },
    },
    defaultTemplate: {
      behaviour: "force-first-document",
      template: {
        source: "inline",
        id: "inline-soap",
      },
      allowUserSelection: false,
    },
  },
  documents: {
    actions: {
      sync: false,
    },
    allowedLanguages: ["en", "da"],
    maxGenerated: 1,
  },
});

Prerequisites

User must be authenticated.

Defaults and omitted values

setInteractionOptions() applies only the option slices you provide. When you omit an option, the embedded Assistant does not apply an override for that setting and keeps the current or product default behavior. Inline templates are available only to the embedded instance that receives the payload. Use an id when another option, such as templates.defaultTemplate, needs to reference the inline template. For personal template section fields, the default editor behavior is:

Field	Default visibility	Default editability
`heading`	Visible	Editable
`description`	Visible	Editable
`miscPrompt`	Hidden	Editable when visible
`outputSchema`	Hidden	Editable when visible

Use visible: true to show a prompt field. Use editable: false to make a visible field read-only.

Template editor section sources

Use templates.sectionSources to control the sections offered by Add section in the Guided Document Generation template editor. templates.sources controls which complete templates are available. Configure the two independently. All fields below are optional. Paths are relative to templates.sectionSources.

Parameter	Type	Definition
`standard.enabled`	`boolean`	Show standard sections. Enabled by default. Set to `false` to hide them.
`standard.include.regions`	`string[]`	Prefer regional section variants and narrow editor language choices. Accepts ISO 3166-1 alpha-2 or alpha-3 codes, such as `BE` or `BEL`.
`standard.include.families`	`string[]`	Show only the listed standard section families, such as `hpi` or `plan`. Matching ignores case and accepts the `corti-` prefix, so `hpi` and `corti-hpi` match the same family.
`project.enabled`	`boolean`	Show project sections. Enabled by default. Set to `false` to hide them.
`project.include.ids`	`string[]`	Show only the listed project section UUIDs.
`project.exclude.ids`	`string[]`	Hide the listed project section UUIDs. Exclusion takes precedence over inclusion.

Standard section filters do not filter project sections. Standard sections support include only. Project sections support both include and exclude by section UUID. Without section source overrides, both sources are enabled with no filters. Partial updates preserve omitted fields, including fields in the other source. For example, setting standard.include.families preserves an earlier project.enabled value. Send [] to clear a list filter; use enabled: false to hide an entire source.

Region and language behavior

For each standard section family, the picker prefers variants matching a configured region. If none match, it prefers variants without a region. If neither exists, it keeps variants from other regions. A region filter therefore does not guarantee that every section has that region. Region selection also narrows the template editor’s language choices within documents.allowedLanguages, or within the supported languages when that option is omitted. With the default supported languages, DK offers Danish, BE offers German, French, and Dutch, and CA offers British English, American English, and French. If no languages match the regions, the editor keeps its otherwise available language choices. A single available language disables the language dropdown. Setting standard.enabled: false disables this region-based language filtering. See Template editor section sources for configuration examples.

Validation and warnings

Boolean fields must be booleans. Filter lists must contain non-empty strings. Corti Assistant trims list values, removes duplicates, and normalizes valid regions to alpha-3 codes. Invalid region codes and malformed project section UUIDs are skipped. Valid remaining values still apply. If no valid values remain in a region or UUID list, that list does not restrict the picker. Corti Assistant reports skipped values through embedded.interactionOptionsWarning. The warning payload adds these fields under skippedValues.templates.sectionSources:

Field	Meaning
`unsupportedSources`	Source blocks ignored because Guided Document Generation is unavailable, either `"standard"` or `"project"`.
`standard.include.regions`	Invalid region values.
`project.include.ids`	Invalid included section UUIDs.
`project.exclude.ids`	Invalid excluded section UUIDs.

For accounts using legacy templates, both section source blocks are ignored. Section family names are normalized but are not checked against a catalog. An unknown family can produce an empty standard section list without a warning.

Input validation

mode.fallback: Must be either "in-person" or "virtual".
mode.options: Must contain one or both of "in-person" and "virtual".
spokenLanguage.fallback: Must be a valid language code when provided.
spokenLanguage.options: Must be an array of valid language codes when provided. If you provide both fallback and options, fallback should be one of the listed options.
templates.sources.personal.enabled: Must be a boolean when provided.
templates.sources.personal.sectionFields: Optional object controlling field-level access in the guided template editor. heading and description accept an optional { editable?: boolean } object. miscPrompt and outputSchema accept an optional { visible?: boolean; editable?: boolean } object.
templates.sources.standard.enabled: Must be a boolean when provided.
templates.sources.standard.include.regions: Must be an array of ISO 3166-1 alpha-3 template region codes when provided.
templates.sources.standard.include.families: Must be an array of standard template family identifiers when provided.
templates.sources.standard.exclude.regions: Must be an array of ISO 3166-1 alpha-3 template region codes when provided.
templates.sources.standard.exclude.families: Must be an array of standard template family identifiers when provided.
templates.sources.project.enabled: Must be a boolean when provided.
templates.sources.project.include.ids: Must be an array of project template UUID strings when provided.
templates.sources.project.exclude.ids: Must be an array of project template UUID strings when provided.
templates.sources.inline.enabled: Must be a boolean when provided.
templates.sources.inline.templates: Must be an array of inline template objects when provided. Inline template IDs only need to be unique within the current setInteractionOptions() payload and are required only when referenced by another option.
templates.defaultTemplate.behaviour: Must be "fallback" or "force-first-document" when provided.
templates.defaultTemplate.template.source: Must be "standard", "project", or "inline" when provided.
templates.defaultTemplate.template.id: Must be a valid template identifier for the selected source when provided. Standard and project templates use UUIDs; inline templates use the local inline template ID.
templates.defaultTemplate.allowUserSelection: Must be a boolean when provided. Set it to false to hide user controls for selecting and persisting a default template.
documents.actions.sync: Must be a boolean when provided.
documents.allowedLanguages: Must be an array of valid BCP 47 locale codes when provided. Region-less codes (e.g., "en", "da") are recommended; region variants (e.g., "en-US") are supported if the region-less code does not provide your desired results.
documents.maxGenerated: Must be a number or "unlimited" when provided. 0 is treated as unlimited.

Possible errors

UNAUTHORIZED: User not authenticated.
INVALID_PAYLOAD: Invalid mode, language, template, or boolean value.
INTERNAL_ERROR: Failed to apply interaction options.

Returns

This method is documented as a configuration action and does not expose a response payload in the current public reference.

Clinical Text Generation

Medical Coding

Clinical Assistant

Usage

Prerequisites

Defaults and omitted values

Template editor section sources

Region and language behavior

Validation and warnings

Input validation

Possible errors

Returns

​Usage

​Prerequisites

​Defaults and omitted values

​Template editor section sources

​Region and language behavior

​Validation and warnings

​Input validation

​Possible errors

​Returns

​Related reference

Usage

Prerequisites

Defaults and omitted values

Template editor section sources

Region and language behavior

Validation and warnings

Input validation

Possible errors

Returns

Related reference