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. All payload properties are required and can be found on the response from authentication service. For convenience, you can simply set the authentication response as the payload directly. PostMessage: 
iframe.contentWindow.postMessage(
  {
    type: "CORTI_EMBEDDED",
    version: "v1",
    action: "auth",
    requestId: "unique-id",
    payload: {
      access_token: string,
      refresh_token: string,
      id_token: string,
      token_type: string,
    },
  },
  "*",
);
Window API: 
const api = window.CortiEmbedded.v1;
const user = await api.auth({
  access_token: string,
  refresh_token: string,
  id_token: string,
  token_type: string,
});
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,
      templateEditor: 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: boolean,
    aiChat: boolean,
    documentFeedback: boolean,
    navigation: boolean,
    virtualMode: boolean,
    syncDocumentAction: boolean,
    templateEditor: boolean,
  },
  appearance: {
    primaryColor: string | null,
  },
  locale: {
    interfaceLanguage: string | null,
    dictationLanguage: string,
    overrides: Record<string, string>,
  },
});
Returns: 
{
  features: {
    interactionTitle: boolean,
    aiChat: boolean,
    documentFeedback: boolean,
    navigation: boolean,
    virtualMode: boolean,
    syncDocumentAction: boolean,
    templateEditor: 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
  • features.templateEditor: true
  • 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
}

​
Configuration Reference

​
Available Interface Languages

Updated as per February 2026
Language codeLanguage
enEnglish
de-DEGerman
fr-FRFrench
it-ITItalian
sv-SESwedish
da-DKDanish
nb-NONorwegian Bokmål
nn-NONorwegian Nynorsk

​
Available Dictation Languages

Updated as per February 2026

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