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

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

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

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

<Tip>
  Use [Configuration Scenarios](/assistant/configuration-scenarios) for
  practical examples and [Supported Values](/assistant/configuration-values) for
  supported languages and other lookup values.
</Tip>

<Warning>
  `templates.sources.standard` and `templates.sources.project` apply only when
  [Guided Document Generation](/release-notes/corti-assistant#v12-19-0) 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`.
</Warning>

## Usage

```typescript theme={null}
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"],
        },
      },
    },
    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              |
| `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. `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](/assistant/api-reference)
* [Supported Values](/assistant/configuration-values)
* [Configuration Scenarios](/assistant/configuration-scenarios)
* [configureSession() (Deprecated)](/assistant/api/configure-session)