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 that receives the structured clinical report generated by SofIA. Assign it as a JS property on the element (el.handleReport = fn) — it is not delivered via an HTML attribute or a DOM event
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
onReportApply	function	Receives the curated report when the doctor clicks Apply in the insertion preview modal. Falls back to handleReport when the modal is disabled
updateTemplate	function	Returns the doctor’s existing EMR field content so generation integrates it. See Pre-fill from your EMR
handleExtras	function	Receives the clinical actions (petitions, appointments, tests…) extracted from the transcript, pass-through. See Clinical Actions (Extras)
onEvent	function	Receives the SDK’s activity events (recording, heartbeat while audio flows, interaction, typing, report, lifecycle). PHI-free payloads. Requires eventSubscriptions. See Activity events

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.

handleExtras

handleExtras: (extras: Record<string, unknown>[]) => void

Called when the user clicks an extras category button (petitions, appointments, tests, referrals…). Receives the array of items for that category, delivered exactly as the model extracted it against your templateExtras schema — the SDK does not rename or transform fields. The shape of each item is defined by your schema. Pairs with the templateExtras prop. See Clinical Actions (Extras).

onEvent

onEvent: (event: SdkEvent) => void
// SdkEvent = { name, family, level, ts, seq, sdkVersion, sessionId, payload }

Called asynchronously with every event you subscribed to via eventSubscriptions (e.g. ['recording.*', 'activity.*', 'report.*']). Without a subscription nothing is delivered. Payloads only contain enums, booleans and numbers — never clinical text or identifiers. Meant for idle detection and for keeping your system’s session alive while the clinician records (recording.heartbeat). See Activity events.

Contextual Data

Property	Type	Default Value	Description
patientdata	string (JSON) | object	undefined	Contextual patient information (background, previous notes, referrals) to enrich clinical processing
templateExtras	string (JSON) | object	undefined	JSON Schema whose top-level properties are the action categories. Each property renders a button that extracts that category from the transcript. JS property el.templateExtras; web-component attribute template-extras. See Clinical Actions (Extras)

Report curation and EMR pre-fill

These props power two report features. See their dedicated guides for the full flow.

Property	Type	Description
onReportApply	function	Fires when the doctor clicks Apply in the insertion preview modal. Receives only the fields the doctor kept/edited
insertionPreviewClassNames	object	Class-name overrides to style the insertion preview modal (which lives in the SDK shadow DOM). Keys: backdrop, panel, header, body, footer, group, row, gapRow, applyButton, cancelButton
updateTemplate	function	Returns the doctor’s existing EMR field content, keyed by template property id, so generated notes integrate what is already documented. See Pre-fill from your EMR

Activity events

Property	Type	Description
onEvent	function	Handler for the event stream. JS property only (el.onEvent = fn)
eventSubscriptions	string[] (JSON)	Which events onEvent receives: exact names ("recording.started"), family wildcards ("recording.*") or "*". Without it no event is delivered. JS property el.eventSubscriptions; web component attribute event-subscriptions

See the full guide, with the event catalogue and the inactivity recipes, in Activity events.

Consent Indicator

The consent status indicator in the header is not a component property. It is enabled through your Omniloy account/profile settings (contact [e-mail] to turn it on). When enabled, the indicator reflects the signedConsent field you provide inside patientdata (see Patient Data) and shows three states: consent signed, not signed, and AI use refused.

Turning this option on does more than show the indicator. If the patient’s signedConsent.aiUse reads "refused", recording and report generation are unavailable in that consultation (recording, dictation, report and clinical actions); the chat stays available, with the reason shown to the doctor. If your HIS does not report aiUse, nothing changes from today’s behaviour.

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.

Analytics context

Property	Type	Default Value	Description
usermedicalspecialty	string	undefined	The doctor’s medical specialty (e.g. "cardiology"). Purely descriptive — it does not change SDK behavior. When set, it is attached to every analytics event (as user_medical_specialty) so usage can be segmented by specialty. Passed through verbatim, with no normalization. Works both as a React prop and as a web-component attribute/property

Breaking change (v1.0.9). usermedicalspecialty replaces the camelCase userMedicalSpecialty that shipped in v1.0.8. The old name is no longer read: a host still passing it gets no error, but the value is silently dropped and events lose the specialty. Rename to the all-lowercase usermedicalspecialty, matching the other string props (userid, patientid, templateid).

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

Data properties go on the element as attributes; callbacks are assigned as JS properties:

<sofia-sdk
  id="sofia"
  patientdata='{"age": 45, "history": "Arterial hypertension"}'
  language="es"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  template='{"type": "object"}'
  templateid="soap-general-v1"
  isopen="true"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Report:', report);
    sofia.setIsOpen = (isOpen) => console.log('Open:', isOpen);
  });
</script>

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
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  language="es"
>
</sofia-sdk>

Advanced configuration with callbacks

<sofia-sdk
  id="sofia"
  debug="true"
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

<script>
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.getElementById('sofia');
    sofia.handleReport = (report) => console.log('Report:', report);
    sofia.setGetLastReport = (getReport) => { window.getLastSofiaReport = getReport; };
  });
</script>

Callbacks are JS properties, not HTML attributes. Assign every callback directly on the element with camelCase (e.g. element.handleReport = fn, element.setIsOpen = fn, element.setGetLastReport = fn, element.onReportApply = fn, element.updateTemplate = fn). There is no handle-report HTML attribute or DOM event — an attribute like handle-report="myFn" will not fire. Simple data properties (isopen, patientdata, debug) use the same lowercase name as both an HTML attribute and a JS property.

Property	Kind	How to set
handleReport	callback	JS property only: el.handleReport = fn
setIsOpen	callback	JS property only: el.setIsOpen = fn
setGetLastReport	callback	JS property only: el.setGetLastReport = fn
onReportApply	callback	JS property only: el.onReportApply = fn
updateTemplate	callback	JS property only: el.updateTemplate = fn
handleExtras	callback	JS property only: el.handleExtras = fn
onEvent	callback	JS property only: el.onEvent = fn
isopen	data	HTML attribute or JS property
patientdata	data	HTML attribute or JS property
templateExtras	data	JS property el.templateExtras or HTML attribute template-extras
eventSubscriptions	data	JS property el.eventSubscriptions or HTML attribute event-subscriptions
debug	data	HTML attribute or JS property

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

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: Assign callbacks programmatically as JS properties on the element (e.g., element.handleReport = fn). They cannot be wired through HTML attributes or global function names.