Recommended use

// open the widget
document.getElementById('heidi-button').addEventListener('click', () => {
  Heidi.open({
    patient: {
      id: '123',
      name: 'John Doe',
      gender: 'Male',
      dob: '1990-01-01',
    },
  });
});
 
// open the widget with a custom template
document.getElementById('heidi-button').addEventListener('click', () => {
  Heidi.open({
    template: templateData, //templateData is your custom template object
    patient: {
      id: '123',
      name: 'John Doe',
      gender: 'Male',
      dob: '1990-01-01',
    },
  });
});

All methods and callbacks

Heidi.open(params?)

Opens Heidi and starts a new session.

• If a sessionId is specified, the widget will open that session.
• If startNewSession is set to true, the widget will create a new session, regardless of whether a sessionId is provided.

The Heidi.open() method accepts an optional params object with the following properties:

Using a custom template

If you specify a custom template, then after transcription, Heidi will generate answers to all the questions in this template.

When Heidi.onPushData(callback) is triggered, Heidi will send back a JSON template with all the answers included. These answers can then be placed back into the relevant fields in your EHR.

Note that these templates are passed when widget is launched. It is a dynamic process that will require you to take the active EHR template and transform it into a JSON format that widget can accept.

Heidi.close(params?)

Close Heidi.

params?: {
  keepSession? : boolean,
  force? : boolean
}

• Set force to true to close Heidi skipping the confirmation step.
• If keepSession is true and force is true, then Heidi will store the current session ID and re-open it when triggered next.

Heidi.onPushData(callback)

Triggered when a user clicks Push Note in the widget.

callback(data): a function called when the user chooses to push notes from the Heidi library to your EHR:

data: {
  noteData: string | Template,
  transcript: string, // only included if `result.includeTranscript` is `true` in the initialisation options
  sessionId: string, // the Heidi session this note is from
  patientInfo: PatientInfo, // the patient information provided in Heidi.open()
  sectionalData?: {  // only included when using sectional note editor (result.sectionalData.enabled = true)
    data: Array<{
      section_id: string,      // the ID of the EHR section (from availableSections)
      section_name: string,    // the name of the EHR section
      content: string          // the note content for this section
    }>
  },
  clinicalCodes?: Array<{  // only included when result.clinicalCoding.enabled = true
    primaryCode: {
      code: string,          // the medical code (e.g., "M17.3")
      codeName: string,      // description of the code
      codeSystem: string     // code system (e.g., "ICD-10-AM")
    },
    similarCodes?: Array<{
      code: string,
      codeName: string,
      codeSystem: string
    }>
  }>,
  observations?: object  // only included if `result.includeObservations` is `true`
}

Field Descriptions:

• noteData contains the note data as a string, if a template was not provided, or following the Template interface.

• sectionalData is included when using the sectional note editor (with result.sectionalData.enabled set to true), providing structured section data that can be mapped to specific fields in your EHR.

• clinicalCodes is included when clinical coding is enabled (with result.clinicalCoding.enabled set to true), providing standardized medical codes (ICD-10, SNOMED, MBS, etc.) for diagnoses and procedures. Each code group contains a primary code and optionally similar/related codes.

Example usage:

Heidi.onPushData((heidiNote) => {
  // Handle full note data
  if (heidiNote.noteData) {
    updateEHRNoteField(heidiNote.noteData);
  }
 
  // Handle sectional data if present
  if (heidiNote.sectionalData) {
    heidiNote.sectionalData.data.forEach((section) => {
      updateEHRField(section.section_id, section.content);
    });
  }
 
  // Handle clinical codes if present
  if (heidiNote.clinicalCodes) {
    heidiNote.clinicalCodes.forEach((codeGroup) => {
      const primary = codeGroup.primaryCode;
 
      // Add primary code to EHR
      addClinicalCode(primary.code, primary.codeSystem);
 
      // Optionally, present similar codes to user for selection
      if (codeGroup.similarCodes) {
        showSimilarCodesDialog(codeGroup.similarCodes);
      }
    });
  }
 
  // Handle observations if present
  if (heidiNote.observations) {
    processObservations(heidiNote.observations);
  }
});

When using the sectional note editor (with result.sectionalData.enabled set to true), the sectionalData field will be included with structured section data that can be mapped to specific fields in your EHR.

Example usage with sectional data:

Heidi.onPushData((heidiNote) => {
  // Handle sectional data if present
  if (heidiNote.sectionalData) {
    heidiNote.sectionalData.data.forEach((section) => {
      // Update your EHR field with the section content
      updateEHRField(section.section_id, section.content);
    });
  }
 
  // Handle full note data if needed
  if (heidiNote.noteData) {
    // Handle the complete note
  }
});

Note: If this callback is not set, the Push Note button will not be available on the UI.

Heidi.onPushDocument(callback)

Triggered when a user clicks Push Document in the widget.

callback(data): a function called when the user chooses to push documents from the Heidi library to your EHR:

data: {
  title: string, // the document's title
  content: string, // the document's content
  sessionId: string, // the Heidi session this note is from
  patientInfo: PatientInfo, // the patient information provided in Heidi.open()
  clinicalCodes?: Array<{  // only included when result.clinicalCoding.enabled = true
    primaryCode: {
      code: string,
      codeName: string,
      codeSystem: string
    },
    similarCodes?: Array<{
      code: string,
      codeName: string,
      codeSystem: string
    }>
  }>
}

Clinical codes are also available in documents when result.clinicalCoding.enabled is set to true. The structure is identical to the clinical codes in Heidi.onPushData().

Example usage:

Heidi.onPushDocument((heidiDocument) => {
  // Save document to EHR
  saveDocument(heidiDocument.title, heidiDocument.content);
 
  // Process clinical codes if present
  if (heidiDocument.clinicalCodes) {
    heidiDocument.clinicalCodes.forEach((codeGroup) => {
      addClinicalCode(codeGroup.primaryCode.code, codeGroup.primaryCode.codeSystem);
    });
  }
});

Note: If this callback is not set, the Push Document button will not be available on the UI.

Heidi.onSessionStarted(callback)

Called with a new Heidi session is started.

callback(sessionId): a function called when a new Heidi Session is created. sessionId is a string containing the current Heidi session ID.

Heidi.onTokenExpired(callback)

When called, use this callback to generate a new token and provide it to the widget via Heidi.setToken.

Heidi.setToken(token)

Update the current token used by Heidi.

Heidi.onOpen(callback)

Called when the widget is opened.

Heidi.onClose(callback)

Called when the widget is closed.

Heidi.setPatient(patientInfo)

Update the patient information for the current session.

Update patient information for the current session.

Heidi.setContext({ context: string, mode?: 'append' | 'overwrite' })

Set context information for the session.

Mode options:

• Default (no mode): Only sets context if none exists yet
• mode: 'append': Appends the new context to any existing context
• mode: 'overwrite': Replaces existing context with the new context

This can be used to set:

• Medications,
• Allergies and,
• any other patient info to enrich Heidi's notes.

Note: we recommend using a string and not structured data as this will be displayed to the practitioners within the widget. Note: There may be a small delay before the context is updated in the widget.

Heidi.onResize(callback)

Called when the user resizes(expands or collapses) the widget.

callback(expanded: boolean): a function called when the user resizes the widget. expanded is a boolean indicating whether the widget is expanded or not.

Heidi.onRecordingStarted(callback)

Called when the user starts a recording.

Heidi.onRecordingPaused(callback)

Called when the user pauses a recording.

Heidi.onRecordingStopped(callback)

Called when the user stops a recording.

Heidi.onRecordingStatusChange(callback)

Called when the recording status changes in the Heidi widget.

callback(status: HeidiRecordingStatus): Invoked whenever the recording status updates, receiving the new status.

export type HeidiRecordingStatus = 'RECORDING' | 'NOT_STARTED' | 'PAUSED' | 'STOPPED';