> ## 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 Reliability, Timeouts, and Recovery

> Recommended timeout and retry patterns for Embedded Assistant lifecycle events.

Use this guidance to keep the host application responsive when an embedded lifecycle event does not arrive. The most important event to guard is [`interaction.loaded`](/assistant/events/generated/interaction/loaded), which confirms that the requested interaction is ready to display after navigation.

<Tip>
  Load the Assistant with `visibility="hidden"`, navigate to the interaction,
  and show the component after you receive
  [`embedded.navigated`](/assistant/events/generated/embedded-api/navigated) or
  [`interaction.loaded`](/assistant/events/generated/interaction/loaded). This
  prevents users from seeing an incomplete embedded state.
</Tip>

## Recommended timeout

Start a timeout whenever your integration initiates navigation that depends on `interaction.loaded`. Use a default timeout between 10 and 30 seconds. Corti recommends starting with 20 seconds, then tuning based on your own network and WebView conditions.

When the timeout expires:

1. Stop waiting for the stale event listener.
2. Show a user-visible recovery state.
3. Provide a retry action that reinitializes the embed, remounts the Web Component, or reloads the iframe.
4. Log the timeout in your own monitoring so your team can separate integration, network, and service issues.

Do not leave users on an indefinite spinner. A clear recovery state is safer than a silent loading screen.

## User-facing recovery copy

Use short copy that explains the state without exposing implementation details:

```text theme={null}
Assistant is taking longer than expected to load.
Check your connection, then try again.
```

Use an action label such as `Retry` or `Reload Assistant`. When the user retries, create a fresh embedded instance or reload the iframe before repeating authentication, configuration, interaction creation, and navigation.

## Minimal implementation

The following example starts a timer before navigation, clears it when `interaction.loaded` arrives, and exposes a retry path that remounts the Web Component.

```ts title="TypeScript" theme={null}
const INTERACTION_LOADED_TIMEOUT_MS = 20000;

type EmbedState = "loading" | "ready" | "recoverable-error";

let interactionLoadedTimer: ReturnType<typeof setTimeout> | undefined;

function setEmbedState(state: EmbedState) {
  // Render your own loading, ready, or retry UI here.
  console.log("Embedded Assistant state:", state);
}

function clearInteractionLoadedTimer() {
  if (interactionLoadedTimer) clearTimeout(interactionLoadedTimer);
  interactionLoadedTimer = undefined;
}

function waitForInteractionLoaded(
  corti: HTMLElement,
  startEmbed: (corti: HTMLElement) => Promise<void>,
) {
  clearInteractionLoadedTimer();
  setEmbedState("loading");

  const handleLoaded = () => {
    clearInteractionLoadedTimer();
    setEmbedState("ready");
  };

  corti.addEventListener("interaction.loaded", handleLoaded, { once: true });

  interactionLoadedTimer = setTimeout(() => {
    corti.removeEventListener("interaction.loaded", handleLoaded);
    setEmbedState("recoverable-error");
  }, INTERACTION_LOADED_TIMEOUT_MS);

  return startEmbed(corti);
}

async function retryEmbed(
  corti: HTMLElement,
  startEmbed: (corti: HTMLElement) => Promise<void>,
) {
  clearInteractionLoadedTimer();
  const freshCorti = corti.cloneNode(false) as HTMLElement;
  corti.replaceWith(freshCorti);

  await waitForInteractionLoaded(freshCorti, startEmbed);
}
```

## What to monitor

Track these signals in your host application:

* Timeout count and timeout rate for `interaction.loaded`
* Browser or WebView family and version
* Assistant region and `baseURL`
* Whether the retry succeeds
* The last Embedded API method called before the timeout

Do not log OAuth tokens, request bodies, transcripts, generated documents, or other sensitive clinical data.

## Related pages

<CardGroup cols={2}>
  <Card title="Web Component API" icon="puzzle-piece" href="/assistant/web-component-api">
    Use the recommended integration method for new embedded deployments.
  </Card>

  <Card title="Events Reference" icon="bolt" href="/assistant/events/index">
    Review lifecycle events emitted by the Embedded Assistant.
  </Card>
</CardGroup>