Widget
SDK specification
Initialisation options

Recommended configuration

const heidiOptions = {
  token: 'JWT_TOKEN',
  target: '#heidi',
  region: 'AU',
  productName: 'Your EMR Name',
  display: {
    position: 'bottom-right',
  },
  language: {
    inputDefault: 'en',
    outputDefault: 'en',
  },
  result: {
    includeTranscript: true,
  },
  onInit: () => {
    // Display the UI that will trigger Heidi
 
    document
      .querySelectorAll('.heidi-button')
      .forEach((button) => (button.style.display = 'block'));
  },
  onReady: () => {
    Heidi.onSessionStarted((sessionId) => {
      // sessionId is the ID of the current Heidi Session.
    });
 
    Heidi.onPushData((data) => {
      // data.notesData will contain data generated by Heidi
      // if a template was used, it will contain the result
      // using the Template structure above
 
      console.log(data);
    });
 
    Heidi.onPushDocument((data) => {
      // data.title and data.content will contain the document data generated by Heidi
 
      console.log(data);
    });
 
    // Note: Heidi.onPushData handles both full notes AND sectional data
    Heidi.onPushData((heidiNote) => {
      // Handle sectional data if present (when result.sectionalData.enabled is true)
      if (heidiNote.sectionalData) {
        heidiNote.sectionalData.data.forEach((section) => {
          console.log(`Section ${section.section_name}: ${section.content}`);
        });
      }
 
      // Handle full note data if present
      if (heidiNote.noteData) {
        console.log('Note data:', heidiNote.noteData);
      }
    });
 
    Heidi.onTokenExpired(() => {
      // refresh the widget token when this callback is called to avoid losing recordings
      // the getToken function below should be replaced with your own logic to get a new token
 
      getToken().then((token) => {
        Heidi.setToken(token);
      });
    });
  }
};

All configuration options

token

A valid JWT token obtained from the Heidi Authentication API.

AttributeValue
OptionalNo
DefaultN/A

target

A target DOM element to render the widget into.

AttributeValue
OptionalYes
Defaultdocument.body

region

A valid code to indicate what Heidi API region to use.

AttributeValue
OptionalYes
DefaultAU
OptionsAU, EU, UK, US, CA

displayLanguage

A language code to indicate what language the widget UI should be displayed in

AttributeValue
OptionalYes
Defaulten
Optionsen, es, de, fr

productName

The name of your EMR product. This is shown to users during the Heidi signup process.

AttributeValue
OptionalYes
DefaultN/A

onInit

Called when Heidi is successfully initialised. This is called as soon as the script is successfully loaded on your page.

AttributeValue
OptionalYes
DefaultN/A

onReady

Called when widget is ready for use. This is called after Heidi.open() is triggered.

AttributeValue
OptionalYes
DefaultN/A

result

Result Options for the widget.

const heidiOptions = {
  // ...
  result: {
    includeTranscript: true, // include transcript in the Heidi note data
    sectionalData: {
      enabled: true, // enable sectional note generation
      availableSections: [
        { section_id: '1', section_name: 'Chief Complaint' },
        { section_id: '2', section_name: 'History of Present Illness' },
        { section_id: '3', section_name: 'Physical Exam' },
        { section_id: '4', section_name: 'Assessment & Plan' }
      ]
    }
  }
  // ...
}

result.includeTranscript

When set to true, the transcript will be included in the note data pushed via Heidi.onPushData().

AttributeValue
OptionalYes
Defaultfalse

result.sectionalData

Enables sectional note generation, where Heidi generates structured notes split into sections that can be mapped to specific fields in your EHR.

When enabled, users can link note sections to EHR sections, and push them using the Heidi.onPushData() callback. The sectional data will be included in the sectionalData field of the HeidiNote object.

sectionalData: {
  enabled: true,
  availableSections: [
    { section_id: 'subjective', section_name: 'Subjective' },
    { section_id: 'objective', section_name: 'Objective' },
    { section_id: 'assessment', section_name: 'Assessment' },
    { section_id: 'plan', section_name: 'Plan' }
  ]
}

Properties:

  • enabled (boolean, required): Set to true to enable sectional data mode
  • availableSections (array, required): List of sections available in your EHR
    • section_id (string): Unique identifier for the section
    • section_name (string): Display name for the section
AttributeValue
OptionalYes
DefaultN/A

Note: When sectionalData is enabled, you should implement the Heidi.onPushData() callback to handle the structured data. The sectional data will be available in the sectionalData field of the HeidiNote object. See Methods and Callbacks for more details.

result.clinicalCoding

Enables automatic clinical coding generation for notes and documents. When enabled, Heidi will generate standardized medical codes (ICD-10, SNOMED, MBS, etc.) and include them in the data pushed via Heidi.onPushData() and Heidi.onPushDocument().

result: {
  enabled: true,  // Must be true to generate clinical codes
  clinicalCoding: {
    enabled: true,
    codeSystems: [
      { codeSystem: 'icd_10_am' },
      { codeSystem: 'mbs_au' },
      { codeSystem: 'achi_13_au' }
    ]
  }
}

Properties:

  • enabled (boolean, required): Set to true to generate clinical codes. If false, no codes will be generated.
  • clinicalCoding.enabled (boolean, required): Set to true to include clinical codes in the onPushData callback.
  • clinicalCoding.codeSystems (array, optional): Filter which code systems to include. If not provided, all generated codes will be included.

Supported Code Systems:

  • snomed_uk - SNOMED CT UK Edition
  • icd_10_cm - ICD-10 Clinical Modification (US)
  • icd_9_cm - ICD-9 Clinical Modification (US)
  • icd_10_uk - ICD-10 UK Edition
  • mbs_au - Medicare Benefits Schedule (Australia)
  • opcs410_uk - OPCS-4.10 UK Procedure Codes
  • icd_10_am - ICD-10 Australian Modification
  • achi_13_au - Australian Classification of Health Interventions
AttributeValue
OptionalYes
DefaultN/A

Clinical Codes Data Structure:

When clinicalCoding.enabled is true, the HeidiNote object passed to Heidi.onPushData() will include a clinicalCodes field:

{
  noteData: "...",
  clinicalCodes: [
    {
      primaryCode: {
        code: "M17.3",
        codeName: "Other post traumatic gonarthrosis",
        codeSystem: "ICD-10-AM"
      },
      similarCodes: [
        {
          code: "M17.0",
          codeName: "Primary gonarthrosis, bilateral",
          codeSystem: "ICD-10-AM"
        },
        {
          code: "M17.1",
          codeName: "Other primary gonarthrosis",
          codeSystem: "ICD-10-AM"
        }
        // ... more similar codes
      ]
    }
    // ... more code groups
  ]
}

Example Usage:

const heidiOptions = {
  // ... other options
  result: {
    enabled: true,  // Generate clinical codes
    clinicalCoding: {
      enabled: true,  // Include codes in onPushData callback
      codeSystems: [
        { codeSystem: 'icd_10_am' },  // Only ICD-10-AM codes
        { codeSystem: 'mbs_au' }      // Only MBS codes
      ]
    }
  }
};
 
// Handle clinical codes in the callback
Heidi.onPushData((heidiNote) => {
  if (heidiNote.clinicalCodes) {
    heidiNote.clinicalCodes.forEach((codeGroup) => {
      const primary = codeGroup.primaryCode;
      console.log(`Primary: ${primary.code} - ${primary.codeName}`);
 
      // Process similar codes
      codeGroup.similarCodes?.forEach((code) => {
        console.log(`Similar: ${code.code} - ${code.codeName}`);
      });
    });
  }
});

Notes:

  • Clinical codes are automatically generated based on the consultation transcript and clinical note content
  • Each code group contains a primary code (most relevant) and optionally similar/related codes
  • If codeSystems is not specified, all generated codes across all systems will be included
  • Clinical codes are also included in Heidi.onPushDocument() when pushing documents

For more details on handling clinical codes, see Methods and Callbacks.

language

Default language options for the widget.

const heidiOptions = {
  // ...
  language: {
    inputDefault: 'en', // the language the transcript will be interpreted with.
    outputDefault: 'en' // the default language a note and documents are generated with.
  }
  // ...
}

See supported languages for a complete list of supported languages.

display

Display options for the widget. See below.

Display Options

theme

The default widget theme.

AttributeValue
OptionalYes
Defaultlight
Optionslight, dark

position

Sets the position of the widget on the page.

AttributeValue
OptionalYes
Defaultbottom-right
Optionstop-left, top-right, bottom-right, bottom-left

maxHeight

Maximum height for the widget when it's fully expanded.

AttributeValue
OptionalYes
Default800
OptionsMinimum recommended is 500px, hover any value will work.

fitToWindow

If set to true, the widget will resize to fill the entire height and width of the window.

AttributeValue
OptionalYes
Defaultfalse

expandable

If set to false, and if fitToWindow is true, the widget will hide the expand button.

AttributeValue
OptionalYes
Defaulttrue

paddingX

Distance of the widget from the window edge (on the X axis - left or right).

AttributeValue
OptionalYes
Default24

paddingY

Distance of the widget from the window edge (on the Y axis - top or bottom).

AttributeValue
OptionalYes
Default24

draggable

Allow the widget to be dragged around the page by the user.

AttributeValue
OptionalYes
Defaultfalse

zIndex

Change the zIndex of the widget frame.

AttributeValue
OptionalYes
Default'10000'