> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sofia/en/sdk/installation#https-protocol) for details.
* **Omniloy credentials** — an `apikey` (and a `baseurl` if your key requires one; Omniloy tells you). Newer keys resolve the endpoint automatically.

<Info>
  **Need credentials?** Email [support@omniloy.com](mailto:support@omniloy.com) 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.
</Info>

## 1. Install

```bash theme={null}
npm install @omniloy/sofia-sdk
```

```javascript theme={null}
// In your entry file (main.js, index.js, etc.)
import '@omniloy/sofia-sdk';
```

Alternatively, load via CDN without a build step:

```html theme={null}
<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.

```html theme={null}
<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>
```

<Warning>
  **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.
</Warning>

<Tip>
  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)](/sofia/en/sdk/templates#accessibility-a11y).
</Tip>

<Tip>
  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.
</Tip>

## 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:

```json theme={null}
{
  "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.

<Tip>
  You can also retrieve the last generated report later using `setGetLastReport`. See [Optional Properties](/sofia/en/sdk/optional-properties) for details.
</Tip>

## 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.

```html theme={null}
<sofia-sdk
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>
```

<Tip>
  **Does your key require a `baseurl`?** Add the one Omniloy assigned you:

  ```html theme={null}
  <sofia-sdk
    apikey="your-legacy-key"
    baseurl="https://your-assigned-endpoint/v1"
    userid="doctor-demo-001"
    patientid="patient-demo-001"
  ></sofia-sdk>
  ```
</Tip>

## Full standalone example

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

```html theme={null}
<!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](/sofia/en/sdk/required-properties)** — understand every configuration parameter
2. **[Clinical Data Schemas](/sofia/en/sdk/templates)** — design schemas for your specialty
3. **[Framework Guides](/sofia/en/sdk/vanilla)** — integrate with React, Angular, or vanilla JS