Skip to content

Quickstart

This page walks through a working integration on staging: get a token, embed the Sahl AI panel, and receive the clinical note in your page. Most teams finish it in under an hour.

Before you begin

You need the following from Sahl AI. Ask your Sahl AI contact or email integrations@sahl.ai.

  • Staging credentials: an integration username and password, issued per organization.
  • Network access to *.sahl.ai and dev.sahl-ai.pages.dev over HTTPS (port 443) from clinician workstations.
  • For the streaming API only: a prompt_id for the summary template you want to use.

Keep credentials on your server

The integration username and password identify your whole organization. Call the login endpoint from your backend. Never put the credentials in browser code, mobile apps or source control.

1. Get an access token

curl -X POST 'https://medipulse-staging.sahl.ai/users/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "<USERNAME>",
    "password": "<PASSWORD>",
    "identifier": "physician@hospital.sa"
  }'

{
  "token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires_in": 86400
}

identifier is the email address of the clinician who is signed in to your EHR. Sahl AI attaches the session, history and preferences to that clinician. See Username and password.

2. Embed the panel

Add an iframe to the page where the clinician documents the encounter. Pass the patient and encounter identifiers in the handshake so the session is linked to the right chart:

<iframe id="sahl-iframe"
        src="https://dev.sahl-ai.pages.dev/iframe-secure"
        allow="microphone; display-capture"
        style="width:100%; height:100%; border:0"></iframe>

const SAHL_ORIGIN = "https://dev.sahl-ai.pages.dev";
const sahlFrame = document.getElementById("sahl-iframe");

window.addEventListener("message", (event) => {
  if (event.origin !== SAHL_ORIGIN) return;
  if (event.source !== sahlFrame.contentWindow) return;

  if (event.data?.type === "SAHL_IFRAME_READY") {
    sahlFrame.contentWindow.postMessage({
      type: "SAHL_IFRAME_INIT",
      payload: {
        access_token: ACCESS_TOKEN, // from step 1, via your backend
        px_id: "PATIENT_ID",
        ex_id: "ENCOUNTER_ID",
        age: 16436, // age in days (45 years)
        gender: "male"
      }
    }, SAHL_ORIGIN);
    return;
  }

  handleSahlData(event.data); // step 3
});

3. Receive the note

When the clinician presses Send to EHR, the panel posts the results to your listener:

function handleSahlData(data) {
  if (data?.type === "icd-automation") {
    // Codification: diagnoses, medications, orders, allergies, examinations
    fillCodedFields(data.data);
  } else if (Array.isArray(data?.summary)) {
    // Clinical note: ordered sections of { title, body[] }
    fillClinicalNote(data.summary);
  }
}

The full shape of each message is in Write-back messages.

Next steps

  • Choose an integration if the embedded panel does not fit your product.
  • Read Secure handshake for the full handshake contract and error handling.
  • Before go-live, ask Sahl AI to load your master lists (drug formulary, order catalogue, frequencies, routes, durations), so the codes you receive match the codes in your EHR.