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.

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 now and track timing in Scheduled Deprecations.

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:

{
  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:

{
  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

1. Replace legacy event names

   Update your event subscriptions from camelCase names to the current dot-notation names, for example recordingStarted to recording.started.

2. Adapt to the current event shape

   Handle the confidential field and update any payload parsing to match the current event reference pages.

3. Remove legacy-only checks

   Remove logic that depends on deprecated: true and stop relying on the legacy event variants during the migration window.

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.

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

Before and after examples

ready

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

{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'ready',
  deprecated: true,
  payload?: {}
}

Replacement: Use embedded.ready instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("ready", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("embedded.ready", ...);

---

loaded

Emitted when navigation to a specific path has completed.

{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'loaded',
  deprecated: true,
  payload: {
    path: string
  }
}

Replacement: Use interaction.loaded instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("loaded", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("interaction.loaded", ...);

---

recordingStarted

Emitted when recording has started.

{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStarted',
  deprecated: true,
  payload?: {}
}

Replacement: Use recording.started instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("recordingStarted", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("recording.started", ...);

---

recordingStopped

Emitted when recording has stopped.

{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStopped',
  deprecated: true,
  payload?: {}
}

Replacement: Use recording.stopped instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("recordingStopped", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("recording.stopped", ...);

---

documentGenerated

Emitted when a document has been generated.

{
  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 instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("documentGenerated", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("document.generated", ...);

---

documentUpdated

Emitted when a document has been updated.

{
  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 instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("documentUpdated", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("document.updated", ...);

---

documentSynced

Emitted when a document has been synced to EHR.

{
  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 instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("documentSynced", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("document.synced", ...);

---

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

{
  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 instead.

Before

const corti = document.querySelector("corti-embedded");

corti.addEventListener("usage", ...);

After

const corti = document.querySelector("corti-embedded");

corti.addEventListener("account.creditsConsumed", ...);

---

Listening for legacy events

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

Current Event Reference

Review the current Embedded API event names, payloads, and generated reference pages.

Scheduled Deprecations

Check rollout timing and upcoming shutdown dates for embedded changes.

Corti Assistant Release Notes

Follow release announcements related to Embedded API changes and migrations.