Optional Properties

Additional settings to customize the SofIA SDK

These properties allow you to customize the behavior and appearance of the SofIA SDK component to fit the specific needs of your implementation.

Active Properties

Interface Control

Property	Type	Default Value	Description
isopen	boolean	true	Component visibility state, allows bidirectional control of the open/closed state. When not provided, the component starts open by default

Callbacks

Property	Type	Description
handleReport	function	Callback function that receives the structured clinical report generated by SofIA. Also available as handle-report attribute. Can be referenced as a global function name
setIsOpen	function	Callback function to handle visibility changes requested by the component
setGetLastReport	function	A callback that receives a function to retrieve the last generated report

Callback Signatures

handleReport

handleReport: (report: Record<string, unknown>) => void

Called when the user triggers report generation. The report object matches the structure defined in your template JSON Schema. Example payload:

{
  "diagnosis": "Type 2 Diabetes Mellitus",
  "treatment_plan": "Metformin 500mg twice daily"
}

setIsOpen

setIsOpen: (isOpen: boolean) => void

Called when the SDK requests a visibility change (e.g., user clicks the close button).

setGetLastReport

setGetLastReport: (getter: () => Promise<Record<string, unknown> | undefined>) => void

Called once during initialization. Provides a function you can store and call later to retrieve the last generated report for the current patient/user session.

Contextual Data

Property	Type	Default Value	Description
patientdata	string (JSON) | object	undefined	Contextual patient information (background, previous notes, referrals) to enrich clinical processing

Consent Indicator

Property	Type	Default Value	Description
showconsentindicator	boolean	false	Show the consent status indicator in the header. Works with the signedConsent field in patientdata

Localization

Property	Type	Default Value	Description
language	string	"es"	Interface language. Supported values: "es" (Spanish), "en" (English)

The default language is "es" (Spanish). If your application targets English-speaking users, set language="en" explicitly.

Debugging

Property	Type	Default Value	Description
debug	boolean	false	Enables detailed logging for debugging purposes

CSS Customization

SofIA SDK renders as a Web Component with Shadow DOM. This prevents style conflicts with the host application, but it also means the application’s global CSS does not directly affect internal SDK elements.

If you need to adjust specific internal styles, inject a <style> tag into the component shadowRoot after the Web Component has been defined and mounted:

async function setupSofIACustomStyles(selector = '#sofia') {
  await customElements.whenDefined('sofia-sdk');
  const sofia = await waitForSofiaComponent(selector);

  const customStyles = `
    :host {
      --sofia-custom-spacing: 12px;
    }

    .omniscribe_chat-view-stick-to-bottom-content {
      font-size: 14px;
    }
  `;

  const existingStyle = sofia.shadowRoot.querySelector('style[data-sofia-custom]');
  const styleTag = existingStyle || document.createElement('style');

  styleTag.setAttribute('data-sofia-custom', 'true');
  styleTag.textContent = customStyles;

  if (!existingStyle) {
    sofia.shadowRoot.appendChild(styleTag);
  }
}

function waitForSofiaComponent(selector) {
  return new Promise((resolve, reject) => {
    let attempts = 0;
    const maxAttempts = 40;

    function check() {
      const sofia = document.querySelector(selector);

      if (sofia?.shadowRoot) {
        resolve(sofia);
        return;
      }

      attempts += 1;
      if (attempts >= maxAttempts) {
        reject(new Error('SofIA is not mounted or has no shadowRoot available'));
        return;
      }

      setTimeout(check, 100);
    }

    check();
  });
}

setupSofIACustomStyles('#sofia').catch((error) => {
  console.warn('Could not apply SofIA custom styles:', error);
});

Use the selector that matches your component, for example #sofia or #sofia-component. In Angular, run this logic in ngAfterViewInit. In AngularJS, call it after configuring the component attributes and callbacks. If the component is mounted conditionally, run the function again after mounting it.

Internal class selectors can change between SDK versions. The selector above matches @omniloy/sofia-sdk 1.0.4. Keep these styles centralized, test the interface when updating @omniloy/sofia-sdk, and prefer documented component properties when they are available.

Manual Report Retrieval

In addition to receiving the report automatically, you can request it on-demand from your application.

The set-get-last-report property executes a callback that provides you with an asynchronous function. You should store this reference to use it whenever you need to retrieve the last generated report.

let getLastReportFn = null;

// Callback assigned to: set-get-last-report
function registerGetter(fn) {
  getLastReportFn = fn;
}

// Example of use in an external button
async function handleSaveClick() {
  if (getLastReportFn) {
    const report = await getLastReportFn();
    console.log("Report retrieved:", report);
  }
}

Usage Examples

Basic setup with patient data

<sofia-sdk
  patientdata='{"age": 45, "history": "Arterial hypertension"}'
  language="es"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
  template='{"type": "object"}'
  templateid="soap-general-v1"
  isopen="true"
  handleReport="handleReport"
  setIsOpen="setIsOpen"
>
</sofia-sdk>

Chat-only mode (no report generation)

To use SofIA in chat-only mode, simply omit the template and templateid properties. The generate button will not appear.

<sofia-sdk
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
  language="es"
>
</sofia-sdk>

Advanced configuration with callbacks

<sofia-sdk
  setGetLastReport="setGetReportFunction"
  handleReport="handleReport"
  debug="true"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
>
</sofia-sdk>

Naming convention for callbacks: When assigning callbacks via JavaScript, use camelCase (e.g., element.handleReport = fn). In HTML attributes, handle-report is also supported as an alias. Simple properties like isopen, patientdata, and debug use the same lowercase name in both HTML and JS.

HTML attribute	JS property	Notes
handle-report or handleReport	handleReport	Both forms work as HTML attribute
setIsOpen	setIsOpen	Use camelCase in HTML
setGetLastReport	setGetLastReport	Use camelCase in HTML
patientdata	patientdata	Same in both
isopen	isopen	Same in both
debug	debug	Same in both

Deprecated Properties

The following properties are deprecated and will be removed in v2.0. They have no effect in the current Chat-based UI architecture.

Property	Migration
toolsargs	Renamed to template. See Required Properties
isonlychat	No longer needed. Chat-only mode is automatic when template/templateid are not provided
disableactions	To disable all actions, do not mount the <sofia-sdk> component
disablegenerate	To hide the generate button, do not pass template/templateid
sofiatitle	No longer configurable. The title is always “SofIA”
isscreenloading	Not available in Chat-based UI
transcriptorselectvalues	Not used in Chat-based UI
render-report-content	Not available in Chat-based UI
handleFill	Not available in Chat-based UI
toast	No longer has effect

Important Notes

• patientdata: Should only contain information necessary for the clinical context, following data minimization principles.
• States: Changes in boolean properties are immediately reflected in the interface.
• Localization: Changing the language affects the entire component interface, including error messages and labels.
• Callbacks: Functions can be referenced by their global name (e.g., handleReport="myFunction" resolves to window.myFunction) or assigned programmatically (e.g., element.handleReport = fn).