Quickstart

Go from zero to a working SofIA integration in 5 minutes

What you’ll build

By the end of this guide, you’ll have SofIA SDK running in your web application — capturing a clinical conversation, generating a structured report, and receiving it in your code via a callback. You’ll see the report object logged to your browser console.

Estimated time: 5 minutes (after receiving credentials)

Prerequisites

• Node.js 18.17.0 or later
• HTTPS enabled in your dev environment (required for audio capture). For local development, use npx local-ssl-proxy or see the Installation guide for details.
• Omniloy credentials — an apikey (and a baseurl if your key requires one; Omniloy tells you). Newer keys resolve the endpoint automatically.

Need credentials? Email [e-mail] with:

• Your company name and project description
• Expected usage (approximate number of consultations/month)
• Whether you need a sandbox environment for testing

The Omniloy team will provide your apikey. For newer keys the SDK resolves the endpoint automatically — no baseurl needed; other keys also come with a baseurl to configure. Omniloy tells you which applies to yours. Typical response time is 1-2 business days.

1. Install

npm install @omniloy/sofia-sdk

// In your entry file (main.js, index.js, etc.)
import '@omniloy/sofia-sdk';

Alternatively, load via CDN without a build step:

<script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>

2. Paste this code

Copy the following into your HTML. Replace the credential placeholder with the value from Omniloy. With a newer key you only need apikey (plus userid/patientid) — the endpoint is auto-selected.

<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
  templateid="quickstart-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Quickstart Consultation",
    "type": "object",
    "properties": {
      "reason_for_visit": {
        "type": "string",
        "description": "Chief complaint or reason for visit"
      },
      "diagnosis": {
        "type": "string",
        "description": "Primary diagnosis"
      },
      "treatment_plan": {
        "type": "string",
        "description": "Recommended treatment"
      }
    },
    "required": ["reason_for_visit", "diagnosis"]
  }'
></sofia-sdk>

<script>
  // Wait for the web component to register
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.querySelector('sofia-sdk');

    // Called when SofIA generates a clinical report
    sofia.handleReport = (report) => {
      console.log('Report received:', report);
      // Process the report in your application:
      // e.g., display it, save it to your EHR, or send it to your backend
    };

    // Called when the component opens or closes
    sofia.setIsOpen = (isOpen) => {
      console.log('SofIA is now', isOpen ? 'open' : 'closed');
    };
  });
</script>

Both template and templateid are required for report generation. Without them, SofIA still works — users can record audio, transcribe conversations, and use the clinical chat — but the generate button will not appear. The template is the JSON Schema that SofIA’s AI agents use to extract structured data from the conversation; without it, there is no schema to fill and no report to generate.

If you need to send visual accessibility preferences in your integration, add the accessibility variable at the same level as template/toolsargs in your configuration payload. See Templates — Accessibility (a11y).

You choose the templateid value — it is your own identifier for this template. Use any descriptive string (e.g., quickstart-v1, soap-notes-v1). It does not need to be registered anywhere beforehand.

3. Run and verify

Open your page in a browser. You should see:

1. SofIA opens automatically — the chat interface appears (default: open)
2. Microphone access prompt — allow it to enable audio transcription
3. Chat interface ready — you can speak or type to interact with SofIA
4. Generate button visible — because both template and templateid are set

After a conversation, click the generate button. Open your browser console (F12 → Console tab). You should see:

Report received: { reason_for_visit: "...", diagnosis: "...", treatment_plan: "..." }

What handleReport returns

The callback receives a plain JavaScript object whose keys match your template schema. No wrapper, no metadata — just the extracted clinical data.

For the schema above, the report looks like:

{
  "reason_for_visit": "Patient reports persistent headache for 3 days",
  "diagnosis": "Tension-type headache",
  "treatment_plan": "Ibuprofen 400mg every 8 hours for 5 days. Follow-up if symptoms persist."
}

The exact values are extracted by SofIA’s AI agents from the consultation conversation and patient context. The keys always correspond to the properties defined in your template schema.

You can also retrieve the last generated report later using setGetLastReport. See Optional Properties for details.

Chat-only mode

If you don’t need report generation, omit template and templateid. SofIA will operate as a clinical chat assistant — no generate button appears.

<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>

Does your key require a baseurl? Add the one Omniloy assigned you:

<sofia-sdk
  apikey="your-legacy-key"
  baseurl="https://your-assigned-endpoint/v1"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>

Full standalone example

Here is a complete HTML file you can save and open directly:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>SofIA SDK — Quickstart</title>
  <script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>
</head>
<body>
  <h1>SofIA Quickstart</h1>

  <sofia-sdk
    apikey="your-api-key"
    userid="doctor-demo-001"
    patientid="patient-demo-001"
    templateid="quickstart-v1"
    template='{
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "Quickstart Consultation",
      "type": "object",
      "properties": {
        "reason_for_visit": { "type": "string", "description": "Chief complaint" },
        "diagnosis": { "type": "string", "description": "Primary diagnosis" },
        "treatment_plan": { "type": "string", "description": "Recommended treatment" }
      },
      "required": ["reason_for_visit", "diagnosis"]
    }'
  ></sofia-sdk>

  <div id="report-output"></div>

  <script>
    customElements.whenDefined('sofia-sdk').then(() => {
      const sofia = document.querySelector('sofia-sdk');

      sofia.handleReport = (report) => {
        console.log('Report received:', report);
        document.getElementById('report-output').innerHTML =
          '<h2>Generated Report</h2><pre>' +
          JSON.stringify(report, null, 2) +
          '</pre>';
      };
    });
  </script>
</body>
</html>

What’s next

1. Required Properties — understand every configuration parameter
2. Clinical Data Schemas — design schemas for your specialty
3. Framework Guides — integrate with React, Angular, or vanilla JS