Required Properties

These properties are mandatory for the correct functioning of the SofIA SDK component. The component will automatically validate the presence and type of each property before establishing the connection.

Quick Reference

All SofIA SDK properties in a single table. For detailed documentation, see Required Properties and Optional Properties.

Property	Type	Default	Status	Description
baseurl	`string`	—	Required	REST API endpoint URL (HTTPS)
wssurl	`string`	—	Required	WebSocket URL for real-time streaming (WSS)
apikey	`string`	—	Required	Authentication key provided by Omniloy
userid	`string`	—	Required	Unique identifier of the healthcare professional
patientid	`string`	—	Required	Unique identifier of the patient for the session
template	`object`	—	Optional	JSON Schema Draft-07 defining the clinical data structure. Enables report generation when used with `templateid`
templateid	`string`	—	Optional	Integrator-defined identifier for the template. Required with `template` to enable report generation
isopen	`boolean`	`true`	Optional	Component visibility state (open/closed)
handleReport	`function`	—	Optional	Callback that receives the generated clinical report
setIsOpen	`function`	—	Optional	Callback for visibility change events
setGetLastReport	`function`	—	Optional	Callback that receives a function to retrieve the last report
patientdata	`string` \| `object`	—	Optional	Contextual patient information for enriched processing
language	`string`	`"es"`	Optional	Interface language (`"es"` or `"en"`)
debug	`boolean`	`false`	Optional	Enables detailed console logging
~~toolsargs~~	`object`	—	Deprecated	Use `template` instead
~~isonlychat~~	`boolean`	—	Deprecated	Auto-detected — omit `template`/`templateid` for chat-only
~~disableactions~~	`boolean`	—	Deprecated	Do not mount the component instead
~~disablegenerate~~	`boolean`	—	Deprecated	Omit `template`/`templateid` instead
~~sofiatitle~~	`string`	—	Deprecated	Title is always “SofIA”
~~isscreenloading~~	`boolean`	—	Deprecated	Not available in Chat-based UI
~~transcriptorselectvalues~~	`array`	—	Deprecated	No effect
~~render-report-content~~	`function`	—	Deprecated	Not available in Chat-based UI
~~handleFill~~	`function`	—	Deprecated	Not available in Chat-based UI
~~toast~~	`function`	—	Deprecated	No effect

For migration guidance on deprecated properties, see the Migration Guide.

Configuration Properties

Property	Type	Description
baseurl	`string`	URL of the SofIA REST API endpoint. Must use HTTPS protocol (e.g.: `https://api.example.com/v1`)
wssurl	`string`	WebSocket URL for real-time streaming. Must use WSS protocol (e.g.: `wss://ws.example.com`)
apikey	`string`	Authentication key provided by Omniloy for access to SofIA services

Session Identifiers

Property	Type	Description
userid	`string`	Unique identifier of the healthcare professional in the EHR/HIS system
patientid	`string`	Unique identifier of the patient for the current session

userid best practices

Use persistent, unique identifiers
Avoid personally identifiable information
Maintain consistency across sessions
Consider using professional license numbers or internal IDs

patientid important notes

Must be unique within your system
Should not contain direct personal identifiers
Can be changed dynamically for different consultations
Must comply with data protection regulations

Changing patientid triggers a full session reset. When you update patientid dynamically, the SDK clears the chat history, closes the current WebSocket connection, and starts a completely new session. The previous conversation context is not carried over to the new patient. Always ensure any pending report generation has completed before switching patients.

Report Generation

These properties enable report generation. When both template and templateid are provided, the generate button becomes available in the interface. Without them, SofIA operates in chat-only mode automatically.

Property	Type	Required	Description
template	`object`	Optional	Complete JSON Schema Draft-07 schema that defines the clinical data structure to generate. Required together with `templateid` to enable report generation. Pass as a JSON string in HTML attributes or as a JavaScript object programmatically
templateid	`string`	Optional	Integrator-defined identifier for the template. Each unique template should have its own `templateid`. Required together with `template` to enable report generation

Deprecated: The toolsargs property has been renamed to template. Use template instead. toolsargs will be removed in v2.0.

`template` (Optional — required for report generation)

JSON Schema defining the structure for clinical data capture. When provided together with templateid, enables the report generation feature and shows the generate button in the interface.

<sofia-sdk template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"Medical Consultation"}'></sofia-sdk>

Schema requirements:

Must be valid JSON Schema Draft-07
Must include $schema property
Should define required fields appropriately
Must not exceed 100KB in size

Example for general consultation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "General Medical Consultation",
  "type": "object",
  "properties": {
    "chief_complaint": {
      "type": "string",
      "description": "Primary reason for visit"
    },
    "diagnosis": {
      "type": "string",
      "description": "Primary diagnosis"
    },
    "treatment_plan": {
      "type": "string",
      "description": "Recommended treatment"
    }
  },
  "required": ["chief_complaint", "diagnosis"]
}

For complex schemas, set the template programmatically via JavaScript instead of inline HTML to avoid JSON escaping issues. See Templates — Passing templates.

`templateid` (Optional — required for report generation)

Integrator-defined identifier that you assign to each template. Must be provided together with template to enable report generation.

<sofia-sdk templateid="soap-general-v1"></sofia-sdk>

How it works:

You choose the templateid value — it is not provided by Omniloy
Each unique template must have its own templateid
SofIA uses this ID to associate configurations and report history on the server
If you reuse the same templateid with a different template schema, the previous configuration will be overwritten

Using the same templateid for different template schemas will overwrite the previous configuration. Always assign a distinct templateid to each template you use.

Naming examples:

"soap-general-v1" — SOAP notes for general practice
"emergency-triage-v2" — emergency department triage
"cardiology-consult-v1" — cardiology consultations
"my-clinic-intake-form" — custom intake form for your clinic

Automatic Validation

The SofIA SDK component performs automatic validation of the required configuration properties:

Type verification: Confirms that each property has the correct type
URL validation: Verifies that baseurl and wssurl use secure protocols (HTTPS/WSS)

Validation Error Messages

When validation fails, the SofIA SDK will display detailed error messages in the browser console and prevent the component from mounting. This ensures that integration issues are identified early in the development process. Example validation error output:

[Sofia SDK] Configuration Error - Missing or invalid required properties:

  • baseurl: API base URL for backend communication
  • wssurl: WebSocket URL for real-time communication
  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional in the EHR/HIS system
  • patientid: Unique identifier of the patient in the EHR/HIS system
    Current value: "INVALID_BASE_URL"
    Current value: "INVALID_WSS_URL"
    Current value: "INVALID_API_KEY"
    Current value: "INVALID_USER_ID"
    Current value: "INVALID_PATIENT_ID"

Component will not mount until all required properties are provided.
Documentation: https://omniloy.mintlify.app/en/sdk/required-properties

Error message components:

Property name: Identifies which property failed validation
Description: Explains the purpose of each property
Current value: Shows the invalid value that was provided (when applicable)
Documentation link: Provides direct access to this reference guide

Component behavior during validation errors:

The SofIA SDK component will not establish connections
No medical data processing will occur
The component remains in a safe, non-functional state
Error messages are logged to help developers identify and resolve issues quickly

For comprehensive troubleshooting of validation errors, see our troubleshooting guide.

Minimal example (chat-only mode)

<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"
></sofia-sdk>

If any required property is missing or invalid, the component will show an error and will not connect to SofIA services.

With report generation

To enable report generation, add both template and templateid:

<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"
  templateid="soap-notes-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": {"type": "string", "description": "Primary diagnosis"}
    },
    "required": ["diagnosis"]
  }'
></sofia-sdk>

Complete Configuration Example

<sofia-sdk
  apikey="sk-your-api-key-here"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  userid="dr-garcia-456"
  patientid="patient-123"
  templateid="emergency-triage-v2"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Emergency Consultation",
    "type": "object",
    "properties": {
      "triage_level": {
        "type": "string",
        "enum": ["1", "2", "3", "4", "5"],
        "description": "Emergency triage level"
      },
      "chief_complaint": {
        "type": "string",
        "description": "Main complaint"
      },
      "vital_signs": {
        "type": "object",
        "properties": {
          "blood_pressure": {"type": "string"},
          "heart_rate": {"type": "number"},
          "temperature": {"type": "number"}
        }
      },
      "diagnosis": {
        "type": "string",
        "description": "Emergency diagnosis"
      },
      "disposition": {
        "type": "string",
        "enum": ["discharge", "admit", "transfer", "observe"],
        "description": "Patient disposition"
      }
    },
    "required": ["triage_level", "chief_complaint", "diagnosis", "disposition"]
  }'>
</sofia-sdk>

Dynamic Configuration

Updating properties programmatically

const sofiaElement = document.querySelector('sofia-sdk');

// Update patient for new consultation
sofiaElement.setAttribute('patientid', 'patient-456');

// Update schema for different specialty
const cardiologySchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Cardiology Consultation",
  "type": "object",
  "properties": {
    "heart_rhythm": {
      "type": "string",
      "enum": ["normal", "irregular", "fast", "slow"]
    },
    "blood_pressure": {
      "type": "string",
      "pattern": "^\\d{2,3}/\\d{2,3}$"
    },
    "ecg_findings": {
      "type": "string"
    }
  },
  "required": ["heart_rhythm", "blood_pressure"]
};

sofiaElement.setAttribute('template', JSON.stringify(cardiologySchema));

Framework-specific configuration

React

const [patientId, setPatientId] = useState('patient-123');
const [template, setTemplate] = useState({
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Clinical Notes",
  "type": "object",
  "properties": {
    "diagnosis": { "type": "string", "description": "Primary diagnosis" }
  },
  "required": ["diagnosis"]
});
const [templateId, setTemplateId] = useState('soap-general-v1');

return (
  <sofia-sdk
    apikey="sk-your-api-key-here"
    baseurl="https://api.example.com/v1"
    wssurl="wss://ws.example.com"
    userid="dr-smith-789"
    patientid={patientId}
    templateid={templateId}
    template={JSON.stringify(template)}
  />
);

Angular

export class AppComponent {
  apiKey = 'sk-your-api-key-here';
  baseUrl = 'https://api.example.com/v1';
  wssUrl = 'wss://ws.example.com';
  userId = 'dr-lopez-456';
  patientId = 'patient-789';
  templateId = 'soap-general-v1';
  schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": { "type": "string", "description": "Primary diagnosis" }
    },
    "required": ["diagnosis"]
  };
  templateJson = JSON.stringify(this.schema);
}

Validation

Property validation checklist

apikey is valid and not expired
baseurl uses HTTPS protocol
wssurl uses WSS protocol
userid is unique and consistent
patientid is unique for the consultation
templateid is unique per template and consistent across sessions (if using report generation)
template is valid JSON Schema Draft-07 (if using report generation)
All required properties are present
No properties exceed size limits

Next Steps

After configuring required properties:

Installation and Configuration

Framework Integration

Features

Support

Quick Reference

Configuration Properties

Session Identifiers

Report Generation

`template` (Optional — required for report generation)

`templateid` (Optional — required for report generation)

Automatic Validation

Validation Error Messages

Minimal example (chat-only mode)

With report generation

Complete Configuration Example

Dynamic Configuration

Updating properties programmatically

Framework-specific configuration

Validation

Property validation checklist

Next Steps

Installation and Configuration

Framework Integration

Features

Support

​Quick Reference

​Configuration Properties

​Session Identifiers

​Report Generation

​template (Optional — required for report generation)

​templateid (Optional — required for report generation)

​Automatic Validation

​Validation Error Messages

​Minimal example (chat-only mode)

​With report generation

​Complete Configuration Example

​Dynamic Configuration

​Updating properties programmatically

​Framework-specific configuration

​Validation

​Property validation checklist

​Next Steps

Quick Reference

Configuration Properties

Session Identifiers

Report Generation

`template` (Optional — required for report generation)

`templateid` (Optional — required for report generation)

Automatic Validation

Validation Error Messages

Minimal example (chat-only mode)

With report generation

Complete Configuration Example

Dynamic Configuration

Updating properties programmatically

Framework-specific configuration

Validation

Property validation checklist

Next Steps