setInteractionOptions()

Reference for the Embedded API setInteractionOptions() method.

Use setInteractionOptions() for interaction-level defaults such as mode, spoken language, template defaults, personal templates, standard templates, project templates, and document actions.

When you set templates.defaultTemplate, it can provide a fallback template for new sessions. 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.

setInteractionOptions() is a one-shot configuration for the embedded instance. Set it before the user starts or opens an interaction.

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

templates.sources.standard and templates.sources.project apply only when Guided Document Generation is enabled for your account. If you send these sources before rollout reaches your environment, the options are inert and do not change behavior. Assistant only dispatches embedded.interactionOptionsWarning with unsupportedSources.

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 },
          contentPrompt: { visible: true, editable: true },
          writingStylePrompt: { visible: true, 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"],
        },
      },
    },
    defaultTemplate: {
      behaviour: "fallback",
      template: {
        source: "standard",
        id: "corti-soap-en",
      },
      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.

For personal template section fields, the default editor behavior is:

Field	Default visibility	Default editability
heading	Visible	Editable
description	Visible	Editable
contentPrompt	Hidden	Editable when visible
writingStylePrompt	Hidden	Editable when visible
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.

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. contentPrompt, writingStylePrompt, 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.defaultTemplate.behaviour: Must be "fallback" when provided.
• templates.defaultTemplate.template.source: Must be "standard" or "project" when provided.
• templates.defaultTemplate.template.id: Must be a valid template identifier for the selected source when provided. Standard templates use fully resolved identifiers such as "corti-soap-en".
• 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.

Related reference

• API Reference Overview
• Supported Values
• Configuration Scenarios
• configureSession() (Deprecated)