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

# Events Migration Guide

> Move from deprecated legacy events to the current Embedded API event format.

Use this guide to move from the legacy event system to the current Embedded API event format.

<Warning>
  Due by 2026-08-20. Legacy events are still dispatched for backward
  compatibility, but support ends on this date. Migrate to the [new event
  format](/assistant/events) now and track timing in [Scheduled
  Deprecations](/assistant/deprecation-timeline).
</Warning>

## Overview

The legacy event system uses the `CORTI_EMBEDDED_EVENT` wrapper format with camelCase event names. These events are still sent alongside the new dot-notation events, but support will be removed in a future release.

## Reference

### Event wrapper differences

The wrapper type stays the same, but the event name and payload contract change.

| Legacy field                   | Current field                  | Notes                                                        |
| ------------------------------ | ------------------------------ | ------------------------------------------------------------ |
| `type: "CORTI_EMBEDDED_EVENT"` | `type: "CORTI_EMBEDDED_EVENT"` | The outer wrapper does not change                            |
| `event: "recordingStarted"`    | `event: "recording.started"`   | Event names move from camelCase to dot notation              |
| `deprecated: true`             | Not present                    | Remove logic that depends on this field                      |
| `payload`                      | `payload`                      | Payloads still exist, but individual event shapes may differ |
| Not present                    | `confidential: boolean`        | Current events include confidentiality metadata              |

### Legacy event structure

All legacy events follow this structure:

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',  // Always this value for legacy events
  event: string,                 // camelCase event name (e.g., 'recordingStarted')
  deprecated: true,              // Always true for legacy events
  payload?: object               // Optional event-specific data
}
```

### New event structure

The new event format uses dot-notation event names and includes a `confidential` field:

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',  // Same wrapper as legacy format
  event: string,                 // Dot-notation event name (e.g., 'recording.started')
  confidential: boolean,         // Indicates if payload contains sensitive data
  payload: object                // Event-specific data with new structure
}
```

### Mapping from legacy event names

| Legacy event        | Current event             |
| ------------------- | ------------------------- |
| `ready`             | `embedded.ready`          |
| `loaded`            | `interaction.loaded`      |
| `recordingStarted`  | `recording.started`       |
| `recordingStopped`  | `recording.stopped`       |
| `documentGenerated` | `document.generated`      |
| `documentUpdated`   | `document.updated`        |
| `documentSynced`    | `document.synced`         |
| `usage`             | `account.creditsConsumed` |

## Migration path

<Steps>
  <Step title="Replace legacy event names">
    Update your event subscriptions from camelCase names to the current dot-notation names, for example `recordingStarted` to `recording.started`.
  </Step>

  <Step title="Adapt to the current event shape">
    Handle the `confidential` field and update any payload parsing to match the
    current event reference pages.
  </Step>

  <Step title="Remove legacy-only checks">
    Remove logic that depends on `deprecated: true` and stop relying on the legacy event variants during the migration window.
  </Step>
</Steps>

<Note>
  The `CORTI_EMBEDDED_EVENT` type wrapper remains the same in both legacy and
  new formats. You still check for
  `event.data?.type === 'CORTI_EMBEDDED_EVENT'`.

  Only the event names and payload structures have changed.
</Note>

<Tip>
  You can use the `deprecated: true` field to programmatically detect and log
  warnings for legacy events in your integration, helping you track migration
  progress.
</Tip>

## Before and after examples

### ready

Emitted when the embedded app is loaded and ready to receive messages.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'ready',
  deprecated: true,
  payload?: {}
}
```

**Replacement:** Use [`embedded.ready`](/assistant/events/generated/embedded-api/ready) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("ready", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("embedded.ready", ...);
    ```
  </div>
</Columns>

***

### loaded

Emitted when navigation to a specific path has completed.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'loaded',
  deprecated: true,
  payload: {
    path: string
  }
}
```

**Replacement:** Use [`interaction.loaded`](/assistant/events/generated/interaction/loaded) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("loaded", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("interaction.loaded", ...);
    ```
  </div>
</Columns>

***

### recordingStarted

Emitted when recording has started.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStarted',
  deprecated: true,
  payload?: {}
}
```

**Replacement:** Use [`recording.started`](/assistant/events/generated/recording/started) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("recordingStarted", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("recording.started", ...);
    ```
  </div>
</Columns>

***

### recordingStopped

Emitted when recording has stopped.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStopped',
  deprecated: true,
  payload?: {}
}
```

**Replacement:** Use [`recording.stopped`](/assistant/events/generated/recording/stopped) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("recordingStopped", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("recording.stopped", ...);
    ```
  </div>
</Columns>

***

### documentGenerated

Emitted when a document has been generated.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentGenerated',
  deprecated: true,
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}
```

**Replacement:** Use [`document.generated`](/assistant/events/generated/document/generated) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("documentGenerated", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("document.generated", ...);
    ```
  </div>
</Columns>

***

### documentUpdated

Emitted when a document has been updated.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentUpdated',
  deprecated: true,
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}
```

**Replacement:** Use [`document.updated`](/assistant/events/generated/document/updated) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("documentUpdated", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("document.updated", ...);
    ```
  </div>
</Columns>

***

### documentSynced

Emitted when a document has been synced to EHR.

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentSynced',
  deprecated: true,
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}
```

**Replacement:** Use [`document.synced`](/assistant/events/generated/document/synced) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("documentSynced", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("document.synced", ...);
    ```
  </div>
</Columns>

***

### usage

Emitted when credits have been consumed because of either of these triggers:

* **Ending/pausing a recording**: credits consumed for transcription and fact extraction
* **Ending dictation**: credits consumed for transcription
* **Generating a document**: credits consumed for text generation

```typescript theme={null}
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'usage',
  payload: {
    creditsConsumed: 0.13,
  }
}
```

This value is not accumulative and only refers to the latest trigger.

**Replacement:** Use [`account.creditsConsumed`](/assistant/events/generated/account/creditsConsumed) instead.

<Columns cols={2}>
  <div>
    **Before**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("usage", ...);
    ```
  </div>

  <div>
    **After**

    ```javascript theme={null}
    const corti = document.querySelector("corti-embedded");

    corti.addEventListener("account.creditsConsumed", ...);
    ```
  </div>
</Columns>

***

### Listening for legacy events

```javascript theme={null}
window.addEventListener("message", (event) => {
  if (event.data?.type === "CORTI_EMBEDDED_EVENT") {
    switch (event.data.event) {
      case "ready":
        console.log("Embedded app ready");
        break;
      case "loaded":
        console.log("Navigation completed:", event.data.payload.path);
        break;
      case "documentGenerated":
        console.log("Document generated:", event.data.payload.document);
        break;
      case "documentUpdated":
        console.log("Document updated:", event.data.payload.document);
        break;
      case "documentSynced":
        console.log("Document synced:", event.data.payload.document);
        break;
      case "recordingStarted":
        console.log("Recording started");
        break;
      case "recordingStopped":
        console.log("Recording stopped");
        break;
      default:
        console.log("Unknown event:", event.data.event);
    }
  }
});
```

## Timeline

* **Current**: Both legacy and new events are dispatched during the migration window
* **Future**: Legacy event support ends on 2026-08-20
* **Action required**: Migrate to the new event format before the deadline

## Related pages

<CardGroup cols={2}>
  <Card title="Current Event Reference" icon="bolt" href="/assistant/events/index">
    Review the current Embedded API event names, payloads, and generated reference pages.
  </Card>

  <Card title="Scheduled Deprecations" icon="clock-3" href="/assistant/deprecation-timeline">
    Check rollout timing and upcoming shutdown dates for embedded changes.
  </Card>

  <Card title="Corti Assistant Release Notes" icon="bookmark" href="/release-notes/corti-assistant">
    Follow release announcements related to Embedded API changes and migrations.
  </Card>
</CardGroup>