Saltar al contenido principal
Una sesión en vivo te permite transmitir una consulta mientras ocurre. Creas la sesión con una llamada REST, recibes una URL de WebSocket, envías el audio mientras el médico habla y recibes la historia clínica generada cuando termina la consulta. Usa esta opción cuando captures el audio en tiempo real. Si ya tienes una grabación terminada, usa en su lugar el flujo de Consultas.

Cómo funciona

  1. POST /v1/scribe-sessions/live devuelve una URL de WebSocket.
  2. Conéctate a esa URL y transmite el audio a medida que se captura.
  3. Envía stop_recording cuando termine la consulta.
  4. El webhook scribe_session.completed te avisa que la historia clínica está lista.
  5. Obtén la historia clínica desde Documentos de historia clínica.

Qué debe tener la API key

La API key que uses aquí necesita cumplir las tres condiciones siguientes; de lo contrario, la llamada falla con 403:
  • El permiso scribe:write, otorgado de forma explícita. Una API key antigua sin el claim de permisos funciona en algunos otros endpoints, pero aquí se rechaza; regenera la API key para obtener una que lo tenga.
  • El rol doctor.
  • Un vínculo con una institución.

Crear una sesión

El cuerpo de la solicitud lleva el contexto de la consulta: de qué consulta se trata, qué plantilla se debe llenar, a qué paciente pertenece y cualquier contexto escrito que ya tengas.
Respuesta:
Trata live.url como un valor opaco y manéjala como un secreto. Conéctate a ella exactamente como se devuelve y no la construyas tú: el host, la ruta y la credencial pueden cambiar sin aviso. La credencial se verifica solo cuando se abre el socket. Una conexión establecida antes de expiresAt puede seguir transmitiendo después de esa hora, y un intento de conexión posterior se rechaza; por eso, solicita una sesión nueva en lugar de reutilizar una URL vencida.

Campos de la solicitud

Elegir la plantilla

template acepta un id o el propio JSON de la plantilla. Envía exactamente uno de los dos. Enviar ambos, o ninguno, devuelve 400 con param igual a template. La forma en línea:
La plantilla en línea se guarda la primera vez que la envías y se reutiliza después: las secciones idénticas se resuelven a la misma plantilla por hash de contenido, así que enviarla en cada consulta no crea duplicados. El formato de las secciones es el mismo que se documenta en Smart Templates, incluidos objetos anidados, arrays y enums.

Identificar al paciente

patient también acepta un id o la identidad en línea. Envía exactamente uno de los dos.
La forma en línea crea al paciente si aún no existe, así que no necesitas llamar antes a la API de Pacientes.

Reintentar la misma consulta

Llamar al endpoint de nuevo con el mismo consultation.id mientras la sesión sigue grabando devuelve la misma sesión con una URL nueva. Esa es la forma admitida de recuperarse de una conexión caída. No compares las dos URL entre sí ni guardes en caché la primera. Una vez detenida la grabación, el mismo id devuelve 409.

Enviar audio

Conéctate a live.url. El servidor envía un mensaje ready cuando está preparado para recibir audio. Envía el audio como frames binarios de WebSocket. Se aceptan dos formatos:
El PCM sin procesar no se inspecciona. Si envías otra frecuencia de muestreo u otro número de canales, el audio se acepta y se transcribe de forma incorrecta, sin error. Un archivo WAV se acepta de la misma manera: su encabezado no se analiza, así que los primeros bytes se convierten en una breve ráfaga de ruido y el resto se transcribe con normalidad. Envía solo las muestras, sin el encabezado.
Envía aproximadamente 100 ms de audio por frame, al ritmo en que se captura. Una carga PCM de menos de 1024 bytes (unos 32 ms) se conserva en la grabación, pero no se reenvía al reconocedor en vivo; por eso, los frames muy pequeños retrasan el texto que ves, pero no hacen que se pierda audio.

Mantener la conexión activa

Envía {"type": "ping", "data": {}} cuando quieras confirmar que el socket está activo; el servidor responde con {"type": "pong", "data": {}}. Cualquier frame entrante, incluido el audio, cuenta como actividad. El servidor cierra una sesión que no recibe nada durante 15 minutos, así que envía audio de forma continua o envía un ping durante las pausas largas.
Un socket por sesión. Abrir una segunda conexión para la misma sesión desplaza a la primera: el socket anterior deja de recibir transcripciones. Reconéctate después de una caída, pero nunca transmitas la misma consulta desde dos lugares a la vez.

Mensajes que recibes

Cada mensaje es JSON con un campo type y un campo data. Una correction reemplaza lo que un transcript informó para el mismo segmento. Si le muestras el texto a un médico, aplica las correcciones a medida que llegan. reconnect puede traer dos motivos. server_draining significa que el servidor se está reiniciando: reconéctate y sigue transmitiendo. resume_upload significa que la orden de detener llegó antes que todo el audio: reconéctate y envía el audio que falta.

Finalizar la sesión

Envía este mensaje cuando termine la consulta:
El servidor termina de procesar el audio que tiene, envía scribe_completed con data.status igual a processing y cierra la conexión.
stop_recording es lo único que genera una historia clínica. Si el socket simplemente se cierra sin él, el audio se conserva, pero no se genera nada, no se dispara ningún webhook y la consulta queda sin terminar. Envíalo siempre, incluso cuando el médico cancela.
El socket no entrega la historia clínica. scribe_completed significa que la generación comenzó, no que terminó. Espera el webhook scribe_session.completed y luego obtén la historia clínica.

Recibir la historia clínica

El webhook scribe_session.completed incluye consultationInternalId, que es el mismo consultation.id que enviaste. Úsalo para obtener la historia clínica:
La finalización suele llegar dentro del minuto siguiente a stop_recording. La generación avanza en parte mientras se transmite el audio, así que una consulta más larga no tarda proporcionalmente más en terminar.
El webhook se dispara unos segundos antes de que el documento se pueda consultar. Si tu primera consulta devuelve una lista vacía, espera 5 segundos y vuelve a intentarlo.

Pérdida de conexión

Reconectarse es normal y seguro.
  • El socket se cae durante la grabación. Vuelve a llamar a POST /v1/scribe-sessions/live con el mismo consultation.id y conéctate a la URL que devuelve. El audio ya recibido se conserva.
  • live.url llega a expiresAt. Solicita una sesión nueva con el mismo consultation.id. Un socket ya abierto no se ve afectado.
  • Cierre 1013. Se puede reintentar: el servidor está ocupado o reiniciándose. Espera un momento y reconéctate.
  • Cierre 1003. El audio no se pudo decodificar. La sesión pasa a estado de error, así que reconectarse no la recupera. Corrige el codificador y empieza una consulta nueva.
  • Cierre 1008. Definitivo: la credencial o la sesión no son válidas. No te reconectes; reintentar da el mismo resultado.

Errores

Consulta Manejo de errores para ver el formato completo de la respuesta.