Skip to main content
This page provides a complete reference for all API actions, events, message types, and return values available in the Corti Embedded Assistant API.

​
Message Types

​
Outgoing Messages (Parent → Embedded)

All messages sent to the embedded app use this structure: 
{
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: string,
  requestId?: string,
  payload?: object
}

​
Incoming Messages (Embedded → Parent)

​
Responses

{
  type: 'CORTI_EMBEDDED_RESPONSE',
  requestId: string,
  success: boolean,
  data?: any,
  error?: {
    message: string,
    code?: string
  }
}

​
Events

{
  type: 'CORTI_EMBEDDED_EVENT',
  event: string,
  payload?: object
}

​
Actions

​
auth

Authenticate the user session with the embedded app. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'auth',
  requestId: 'unique-id',
  payload: {
    mode: 'stateless' | 'stateful', // we currently do not take this value into account and will always refresh the token internally
    access_token: string,
    refresh_token?: string,
    id_token?: string,
    expires_in?: number,
    token_type?: string
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
const user = await api.auth({
  mode: "stateful",
  access_token: "token",
  refresh_token: "refresh-token",
});
Returns: 
{
  id: string,
  email: string
}

​
configure

Configure the Assistant interface for the current session, including toggling UI features, visual appearance, and locale settings. PostMessage: 
iframe.contentWindow.postMessage({
  type: "CORTI_EMBEDDED",
  version: "v1",
  action: "configure",
  payload: {
    features: {
      interactionTitle: boolean,
      aiChat: boolean,
      documentFeedback: boolean,
      navigation: boolean,
      virtualMode: boolean,
      syncDocumentAction: boolean,
    },
    appearance: {
      primaryColor: string | null,
    },
    locale: {
      interfaceLanguage: string | null,
      dictationLanguage: string,
      overrides: Record<string, string>,
    },
  },
}, "*");
Window API: 
const api = window.CortiEmbedded.v1;
const config = await api.configure({
  features: {
    interactionTitle: false,
    aiChat: false,
    documentFeedback: false,
    navigation: true,
    virtualMode: true,
    syncDocumentAction: false,
  },
  appearance: {
    primaryColor: "#00a6ff",
  },
  locale: {
    interfaceLanguage: "de-DE",
    dictationLanguage: "da-DK",
    overrides: {
      key: "value",
    },
  },
});
Returns: 
{
  features: {
    interactionTitle: boolean,
    aiChat: boolean,
    documentFeedback: boolean,
    navigation: boolean,
    virtualMode: boolean,
    syncDocumentAction: boolean,
  },
  appearance: {
    primaryColor: string | null,
  },
  locale: {
    interfaceLanguage: string | null,
    dictationLanguage: string,
    overrides: Record<string, string>,
  }
}
Defaults:
  • features.interactionTitle: true
  • features.aiChat: true
  • features.documentFeedback: true
  • features.navigation: false
  • features.virtualMode: true
  • features.syncDocumentAction: false
  • appearance.primaryColor: null (uses built-in styles)
  • locale.interfaceLanguage: null (uses user’s default or browser setting)
  • locale.dictationLanguage: "en"
  • locale.overrides: {}
Note: The command can be invoked with a partial object, and only the specified properties will take effect. Returns the full currently applied configuration object.

​
createInteraction

Create a new interaction session. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'createInteraction',
  requestId: 'unique-id',
  payload: {
    assignedUserId: string | null,
    encounter: {
      identifier: string,
      status: string,
      type: string,
      period: {
        startedAt: string,
      },
      title: string,
    },
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
const interaction = await api.createInteraction({
  assignedUserId: null,
  encounter: {
    identifier: `encounter-${Date.now()}`,
    status: "planned",
    type: "first_consultation",
    period: {
      startedAt: new Date().toISOString(),
    },
    title: "Initial Consultation",
  },
});
Returns: 
{
  id: string,
  title: string,
  state: string,
  // ... (see getStatus response for full structure)
}

​
addFacts

Add contextual facts to the current interaction. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'addFacts',
  requestId: 'unique-id',
  payload: {
    facts: Array<{
      text: string,
      group: string
    }>
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.addFacts({
  facts: [
    { text: "Chest pain", group: "other" },
    { text: "Shortness of breath", group: "other" },
    { text: "Fatigue", group: "other" },
  ],
});
Returns: void

​
configureSession

Set session-level defaults and preferences. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'configureSession',
  requestId: 'unique-id',
  payload: {
    defaultLanguage: string,
    defaultOutputLanguage: string,
    defaultTemplateKey: string,
    defaultMode: 'virtual' | 'live'
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.configureSession({
  defaultLanguage: "en",
  defaultOutputLanguage: "en",
  defaultTemplateKey: "corti-soap",
  defaultMode: "virtual",
});
Returns: void
Navigate to a specific path within the embedded app. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'navigate',
  requestId: 'unique-id',
  payload: {
    path: string
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.navigate({
  path: "/session/interaction-123",
});
Returns: void Navigable URLs:
  • / – start a new session
  • /session/<id> - go to an existing session identified by <id>
  • /templates - browse and create templates
  • /settings/preferences - edit defaults like languages and default session settings
  • /settings/input - edit dictation input settings
  • /settings/account - edit general account settings
  • /settings/archive - view items in and restore from archive (only relevant if navigation is visible)

​
setCredentials

Change the credentials of the currently authenticated user. Can be used to set credentials for a user without a password (if only authenticated via identity provider) or to change the password of a user with an existing password. Password Policy:
  • At least 1 uppercase, 1 lowercase, 1 numerical and 1 special character
  • At least 8 characters long
PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'setCredentials',
  requestId: 'unique-id',
  payload: {
    password: string
  }
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.setCredentials({ password: "new-password" });
Returns: void

​
startRecording

Start recording within the embedded session. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'startRecording',
  requestId: 'unique-id'
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.startRecording();
Returns: void

​
stopRecording

Stop recording within the embedded session. PostMessage: 
iframe.contentWindow.postMessage({
  type: 'CORTI_EMBEDDED',
  version: 'v1',
  action: 'stopRecording',
  requestId: 'unique-id'
}, '*');
Window API: 
const api = window.CortiEmbedded.v1;
await api.stopRecording();
Returns: void

​
getStatus

Request information about the current state of the application, including authentication status, current user, current URL and interaction details. PostMessage: 
iframe.contentWindow.postMessage({
  type: "CORTI_EMBEDDED",
  version: "v1",
  action: "getStatus",
  requestId: "unique-id"
}, "*");
Window API: 
const api = window.CortiEmbedded.v1;
const status = await api.getStatus();
Returns: 
{
  auth: {
    isAuthenticated: boolean,
    user: {
      id: string,
      email: string
    } | null
  },
  currentUrl: string,
  interaction: {
    id: string,
    title: string,
    state: "planned" | "ongoing" | "paused" | "disconnected" | "ending" | "parsing" | "ended",
    startedAt: string,
    endedAt: string | null,
    endsAt: string | null,
    transcripts: Array<{
      utterances: Array<{
        id: string,
        start: number,
        duration: number,
        text: string,
        isFinal: boolean,
        participantId: string | undefined,
      }>,
      participants: Array<{
        id: string,
        channel: number,
        role: "agent" | "patient" | "other" | "multiple"
      }>,
      isMultiChannel: boolean
    }>,
    documents: Array<{
      id: string,
      name: string,
      templateRef: string,
      isStream: boolean,
      sections: Array<{
        key: string,
        name: string,
        text: string,
        sort: number,
        createdAt: string,
        updatedAt: string,
        markdown: string | undefined | null,
        htmlText: string | undefined,
        plainText: string | undefined,
      }>,
      outputLanguage: string,
    }>,
    facts: Array<{
      id: string,
      text: string,
      group: string,
      isDiscarded: boolean,
      source: "core" | "system" | "user",
      createdAt: string | undefined,
      updatedAt: string,
      isNew: boolean,
      isDraft: boolean | undefined,
    }>,
    websocketUrl: string
  } | null
}

​
Events

The embedded app sends events to notify the parent application of important state changes. All events use the CORTI_EMBEDDED_EVENT message type.

​
ready

Emitted when the embedded app is loaded and ready to receive messages. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'ready',
  payload?: {}
}

​
loaded

Emitted when navigation to a specific path has completed. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'loaded',
  payload: {
    path: string
  }
}

​
recordingStarted

Emitted when recording has started. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStarted',
  payload?: {}
}

​
recordingStopped

Emitted when recording has stopped. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'recordingStopped',
  payload?: {}
}

​
documentGenerated

Emitted when a document has been generated. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentGenerated',
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}

​
documentUpdated

Emitted when a document has been updated. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentUpdated',
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}

​
documentSynced

Emitted when a document has been synced to EHR. 
{
  type: 'CORTI_EMBEDDED_EVENT',
  event: 'documentSynced',
  payload: {
    document: {
      id: string,
      name: string,
      templateRef: string,
      // ... (see getStatus response for full document structure)
    }
  }
}

​
Listening for Events

Listening for 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);
    }
  }
});

​
Configuration Reference

​
Available Interface Languages

Updated as per November 2025
Language codeLanguage
enEnglish
de-DEGerman
fr-FRFrench
it-ITItalian
sv-SESwedish
da-DKDanish

​
Available Dictation Languages

Updated as per November 2025

​
EU

Language codeLanguage
enEnglish
en-GBBritish English
deGerman
frFrench
svSwedish
daDanish
nlDutch
noNorwegian

​
US

Language codeLanguage
enEnglish

​
Known Strings to Override

Currently, only the following keys are exposed for override:
KeyDefault valuePurpose
interview.document.syncDocument.label”Synchronize document”The button text for the “synchronize document” button if enabled.

​
Appearance Configuration

Disclaimer - always ensure WCAG 2.2 AA conformance
Corti Assistant’s default theme has been evaluated against WCAG 2.2 Level AA and meets applicable success criteria in our supported browsers. This conformance claim applies only to the default configuration. Customer changes (e.g., color palettes, CSS overrides, third-party widgets, or content) are outside the scope of this claim. Customers are responsible for ensuring their customizations continue to meet WCAG 2.2 AA (including color contrast and focus visibility). When supplying a custom accent or theme, Customers must ensure WCAG 2.2 AA conformance, including:
  • 1.4.3 Contrast (Minimum): normal text ≥ 4.5:1; large text ≥ 3:1
  • 1.4.11 Non-text Contrast: UI boundaries, focus rings, and selected states ≥ 3:1
  • 2.4.11 Focus Not Obscured (Minimum): focus indicators remain visible and unobstructed
Corti provides accessible defaults. If you override them, verify contrast for all states (default, hover, active, disabled, focus) and on all backgrounds you use.
Please contact us for help or questions.