Guía de Integración: Asistente Speaknosis (Deep Linking)

Esta documentación detalla cómo invocar la aplicación Speaknosis desde cualquier plataforma web externa utilizando el protocolo personalizado speaknosis://. Este método permite levantar el asistente inteligente directamente en el Sistema Operativo del médico, preparándolo para capturar audio y procesar notas clínicas durante una sesión de telemedicina.

1. Conceptos Básicos

La integración se basa en Deep Linking. Para que esto funcione, el médico debe tener instalada la aplicación Speaknosis en su ordenador. Al llamar al protocolo, la aplicación se abrirá automáticamente en modo "Pop-up" por encima de la ventana de telemedicina.

Base del Protocolo: speaknosis://pop-up/?{parámetros}

---

2. Flujo de Autenticación

Antes de invocar el protocolo, la plataforma cliente debe obtener un token de acceso temporal para asegurar la sesión del médico.

---

3. Estructura de la URL (Parámetros)

Para levantar el asistente con el contexto correcto de la cita médica, se deben enviar los siguientes parámetros en la query string:

Parámetro	Tipo	Descripción
view	string	Define la vista inicial. Usar analysis para el asistente de grabación.
token	string	Token de acceso obtenido en el paso anterior.
doctorId	string	Identificador único del médico en el sistema.
appointmentId	string	ID único de la cita actual (se usará para la posterior devolución de datos).

---

4. Ejemplo de Implementación (JavaScript)

Se recomienda el siguiente patrón para asegurar que el navegador procese correctamente la apertura de la aplicación instalada:

/**
 * Levanta el asistente Speaknosis para una cita de telemedicina.
 * @param {string} token - Token de acceso válido.
 * @param {string} doctorId - ID del médico.
 * @param {string} appointmentId - ID de la consulta actual.
 */
async function openSpeaknosisAssistant(token, doctorId, appointmentId) {
  const data = {
    view: "analysis",
    token: token,
    doctorId: doctorId,
    appointmentId: appointmentId,
  };

  const urlParams = new URLSearchParams(data);
  const finalProtocolUrl = `speaknosis://pop-up/?${urlParams}`;

  // Intento de apertura. 
  // Nota: Algunos navegadores requieren un pequeño retraso o doble llamado 
  // para asegurar que el protocolo externo sea detectado.
  window.location.href = finalProtocolUrl;
  
  await new Promise((resolve) => setTimeout(resolve, 400));
  window.location.href = finalProtocolUrl;
}

---

5. Experiencia de Usuario y Funcionamiento

1. Activación: El médico hace clic en un botón (ej: "Activar Asistente IA") dentro de la plataforma de telemedicina.
2. Lanzamiento: El navegador solicita permiso para abrir "Speaknosis" (solo la primera vez).
3. Pop-up: La aplicación se abre en una ventana flotante pequeña que se mantiene siempre visible (Always on Top).
4. Captura de Audio: El asistente comienza a escuchar el audio entrante (sistema) y el micrófono del médico para transcribir la consulta de telemedicina.
5. Finalización: Una vez que el médico aprueba las notas en el asistente, Speaknosis enviará la información procesada al Webhook o API configurada.

6. Consideraciones Técnicas

• Contexto: El appointmentId es crítico. Debe ser el mismo que el cliente usará después para consultar o recibir los resultados de la nota clínica en su base de datos.
• Compatibilidad: Funciona en Windows y macOS siempre que la aplicación de escritorio esté instalada.