Saltar al contenido principal

​
Lo que vas a construir

Al final de esta guía, tendrás SofIA SDK funcionando en tu aplicación web — capturando una conversación clínica, generando un reporte estructurado y recibiéndolo en tu código a través de un callback. Verás el objeto del reporte en la consola de tu navegador. Tiempo estimado: 5 minutos (después de recibir credenciales)

​
Requisitos previos

  • Node.js 18.17.0 o superior
  • HTTPS habilitado en tu entorno de desarrollo (requerido para captura de audio). Para desarrollo local, usa npx local-ssl-proxy o consulta la guia de instalacion para mas detalles.
  • Credenciales Omniloy (apikey, baseurl, wssurl)
¿Necesitas credenciales? Envía un email a support@omniloy.com con:
  • Tu nombre de empresa y descripción del proyecto
  • Uso esperado (número aproximado de consultas/mes)
  • Si necesitas un entorno sandbox para pruebas
El equipo de Omniloy te proporcionará tu apikey, baseurl y wssurl para entornos sandbox y producción. El tiempo de respuesta habitual es de 1-2 días laborables.

​
1. Instalar

npm install @omniloy/sofia-sdk

// En tu archivo de entrada (main.js, index.js, etc.)
import '@omniloy/sofia-sdk';
Alternativamente, carga vía CDN sin necesidad de build: 
<script src="https://unpkg.com/@omniloy/sofia-sdk@latest/dist/webcomponents.umd.js"></script>

​
2. Pega este código

Copia lo siguiente en tu HTML. Reemplaza los tres placeholders de credenciales con los valores de Omniloy. 
<sofia-sdk
  baseurl="https://YOUR_BASE_URL"
  wssurl="wss://YOUR_WSS_URL"
  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": "Consulta Quickstart",
    "type": "object",
    "properties": {
      "motivo_consulta": {
        "type": "string",
        "description": "Motivo principal de la consulta"
      },
      "diagnostico": {
        "type": "string",
        "description": "Diagnóstico principal"
      },
      "plan_tratamiento": {
        "type": "string",
        "description": "Tratamiento recomendado"
      }
    },
    "required": ["motivo_consulta", "diagnostico"]
  }'
></sofia-sdk>

<script>
  // Esperar a que el web component se registre
  customElements.whenDefined('sofia-sdk').then(() => {
    const sofia = document.querySelector('sofia-sdk');

    // Se ejecuta cuando SofIA genera un reporte clínico
    sofia.handleReport = (report) => {
      console.log('Reporte recibido:', report);
      // Procesa el reporte en tu aplicación:
      // ej., mostrarlo, guardarlo en tu EHR, o enviarlo a tu backend
    };

    // Se ejecuta cuando el componente se abre o cierra
    sofia.setIsOpen = (isOpen) => {
      console.log('SofIA está', isOpen ? 'abierto' : 'cerrado');
    };
  });
</script>
Tanto template como templateid son necesarios para la generación de reportes. Sin ellos, SofIA sigue funcionando — los usuarios pueden grabar audio, transcribir conversaciones y usar el chat clínico — pero el botón de generar no aparecerá. El template es el JSON Schema que los agentes de IA de SofIA usan para extraer datos estructurados de la conversación; sin él, no hay esquema que llenar ni reporte que generar.
Si necesitas enviar preferencias visuales de accesibilidad en tu integración, añade la variable accessibility al mismo nivel de template/toolsargs en tu payload de configuración. Ver Templates — Accesibilidad (a11y).
Tu eliges el valor de templateid — es tu propio identificador para esta plantilla. Usa cualquier cadena descriptiva (por ejemplo, quickstart-v1, soap-notes-v1). No necesita estar registrado en ningun lugar previamente.

​
3. Ejecutar y verificar

Abre tu página en el navegador. Deberías ver:
  1. SofIA se abre automáticamente — la interfaz de chat aparece (por defecto: abierta)
  2. Solicitud de acceso al micrófono — permítelo para habilitar la transcripción de audio
  3. Interfaz de chat lista — puedes hablar o escribir para interactuar con SofIA
  4. Botón de generar visible — porque tanto template como templateid están configurados
Después de una conversación, haz clic en el botón generar. Abre la consola del navegador (F12 → pestaña Consola). Deberías ver: 
Reporte recibido: { motivo_consulta: "...", diagnostico: "...", plan_tratamiento: "..." }

​
Qué devuelve handleReport

El callback recibe un objeto JavaScript plano cuyas claves coinciden con tu schema template. Sin wrapper, sin metadata — solo los datos clínicos extraídos. Para el schema anterior, el reporte se ve así: 
{
  "motivo_consulta": "Paciente refiere cefalea persistente de 3 días",
  "diagnostico": "Cefalea tensional",
  "plan_tratamiento": "Ibuprofeno 400mg cada 8 horas durante 5 días. Control si persisten los síntomas."
}
Los valores exactos son extraídos por los agentes de IA de SofIA a partir de la conversación de la consulta y el contexto del paciente. Las claves siempre corresponden a las properties definidas en tu schema template.
También puedes obtener el último reporte generado posteriormente usando setGetLastReport. Consulta Propiedades Opcionales para más detalles.

​
Modo solo chat

Si no necesitas generación de reportes, omite template y templateid. SofIA operará como asistente de chat clínico — no aparece el botón de generar. 
<sofia-sdk
  baseurl="https://YOUR_BASE_URL"
  wssurl="wss://YOUR_WSS_URL"
  apikey="your-api-key"
  userid="doctor-demo-001"
  patientid="patient-demo-001"
></sofia-sdk>

​
Ejemplo completo standalone

Aquí tienes un archivo HTML completo que puedes guardar y abrir directamente: 
<!DOCTYPE html>
<html lang="es">
<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
    baseurl="https://YOUR_BASE_URL"
    wssurl="wss://YOUR_WSS_URL"
    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": "Consulta Quickstart",
      "type": "object",
      "properties": {
        "motivo_consulta": { "type": "string", "description": "Motivo de consulta" },
        "diagnostico": { "type": "string", "description": "Diagnóstico principal" },
        "plan_tratamiento": { "type": "string", "description": "Tratamiento recomendado" }
      },
      "required": ["motivo_consulta", "diagnostico"]
    }'
  ></sofia-sdk>

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

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

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

​
Próximos pasos

  1. Propiedades Requeridas — entiende cada parámetro de configuración
  2. Esquemas de Datos Clínicos — diseña schemas para tu especialidad
  3. Guías por Framework — integra con React, Angular o vanilla JS