Sesiones en Vivo

Una sesión en vivo le permite transmitir una consulta mientras ocurre. Usted crea la sesión con una llamada REST, recibe una URL de WebSocket, envía el audio mientras el médico habla y recibe el registro médico generado cuando termina la consulta. Use esto cuando capture audio en tiempo real. Cuando ya tenga una grabación finalizada, use el flujo de Consultas.

Cómo funciona

POST /v1/scribe-sessions/live devuelve una URL de WebSocket.
Conéctese a esa URL y transmita el audio a medida que se captura.
Envíe stop_recording cuando termine la consulta.
El webhook scribe_session.completed (webhooks) le indica que el registro está listo.
Obtenga el registro desde Documentos de Registro Médico.

Qué debe tener la clave API

La clave que use aquí necesita las tres condiciones siguientes, o la llamada falla con 403:

El permiso scribe:write, otorgado de forma explícita. Una clave antigua sin el claim de permisos funciona en otros endpoints, pero aquí se rechaza; regenere la clave para obtener una válida.
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: cuál es la consulta, qué plantilla se completa, a qué paciente pertenece y el contexto escrito que usted ya tenga.

curl -X POST https://scribe-api.telepatia.ai/v1/scribe-sessions/live \
  -H "Authorization: Bearer SU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "consultation": { "id": "CONSULT-12345", "modality": "IN_PERSON" },
    "template": { "id": "mrc_a1b2c3d4e5f6g7h8" },
    "patient": { "id": "sp_a1b2c3d4e5f6g7h8" },
    "context": {
      "notes": "Patient reports headache since Monday.",
      "pastMedicalHistory": "Hypertension diagnosed 2020."
    }
  }'

Respuesta:

{
  "consultation": { "id": "CONSULT-12345" },
  "status": "created",
  "live": {
    "url": "wss://audio.telepatia.ai/v1/ws/audio/b0cf283f-ab53-51ea-8313-f9c90b38fd1f?token=eyJhbGciOi...",
    "expiresAt": "2026-08-13T22:14:49+00:00"
  }
}

Trate live.url como opaca y manéjela como un secreto. Conéctese exactamente a la URL devuelta y no la construya usted mismo: el host, la ruta y la credencial cambian sin aviso. La credencial se verifica solo cuando el socket se abre. Una conexión establecida antes de expiresAt sigue transmitiendo después de ese instante, y una conexión intentada después se rechaza, así que solicite una sesión nueva en lugar de reutilizar una URL vencida.

Campos de la solicitud

Campo	Obligatorio	Notas
`consultation.id`	sí	Su propio id de consulta. Es la clave de idempotencia y el id con el que obtiene el registro después
`consultation.modality`	no	`IN_PERSON` o `TELEMEDICINE`. `DICTATION` se rechaza aquí: un informe dictado tiene su propio flujo
`template`	sí	Un id o el JSON de la plantilla. Vea abajo
`patient`	sí	Un paciente existente por id, o la identidad del paciente en línea. Vea abajo
`context.notes`	no	Texto libre, hasta 10000 caracteres, usado en la generación del registro
`context.pastMedicalHistory`	no	Texto libre, hasta 10000 caracteres, usado en la generación del registro

Elegir la plantilla

template acepta un id o el propio JSON de la plantilla. Envíe exactamente uno de los dos.

Campo	Envíe esto cuando
`template.id`	La plantilla ya existe en Telepatia. Use el id público de una Smart Template (`mrc_...`) o de una Plantilla de Sesión (`ssc_...`)
`template.sections`	Su sistema es dueño de la plantilla. Envíe la estructura en línea, sin paso de registro

Enviar ambos, o ninguno, devuelve 400 con param igual a template. La forma en línea:

{
  "consultation": { "id": "CONSULT-12345", "modality": "IN_PERSON" },
  "template": {
    "sections": {
      "chiefComplaint": {
        "schema": { "type": "string", "instructions": "El motivo principal de consulta del paciente." },
        "systemPrompt": "Resuma el motivo de consulta."
      },
      "assessment": {
        "schema": { "type": "string", "instructions": "Evaluación clínica y plan." },
        "systemPrompt": "Escriba la evaluación y el plan."
      }
    }
  },
  "patient": { "id": "sp_a1b2c3d4e5f6g7h8" }
}

La plantilla en línea se almacena la primera vez que la envía y se reutiliza después: secciones idénticas 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 documentado en Smart Templates, incluidos objetos anidados, arreglos y enums.

Identificar al paciente

patient también acepta un id o la identidad en línea. Envíe exactamente uno.

{
  "patient": {
    "name": "John Doe",
    "document": { "country": "BR", "type": "CPF", "value": "123.456.789-00" }
  }
}

La forma en línea crea al paciente cuando aún no existe, así que no necesita 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 compare las dos URL entre sí y no almacene la primera. Una vez detenida la grabación, el mismo id devuelve 409.

Enviar audio

Conéctese a live.url. El servidor envía un mensaje ready cuando está preparado para recibir audio. Envíe el audio como frames binarios de WebSocket. Se aceptan dos formatos:

Formato	Requisito
PCM en bruto	16 kHz, mono, 16 bits con signo little-endian
Opus	Dentro de un contenedor Ogg o WebM

El PCM en bruto no se inspecciona. Si envía otra frecuencia de muestreo o 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 un breve ruido y el resto se transcribe con normalidad. Envíe solo las muestras, sin el encabezado.

Envíe aproximadamente 100 ms de audio por frame, al ritmo en que se captura. Una carga PCM menor a 1024 bytes (cerca de 32 ms) se conserva en la grabación, pero no se reenvía al reconocedor en vivo, así que los frames muy pequeños retrasan el texto que usted ve en lugar de perder audio.

Mantener la conexión viva

Envíe {"type": "ping", "data": {}} cuando quiera confirmar que el socket está sano; el servidor responde con {"type": "pong", "data": {}}. Cualquier frame entrante, incluido el audio, cuenta como actividad. Una sesión que no recibe nada durante 15 minutos es cerrada por el servidor, así que envíe audio de forma continua, o haga ping durante las pausas largas.

Un socket por sesión. Abrir una segunda conexión para la misma sesión expulsa a la primera: el socket anterior deja de recibir transcripciones. Reconéctese después de una caída, pero nunca transmita la misma consulta desde dos lugares a la vez.

Mensajes que usted recibe

Cada mensaje es JSON con un campo type y un campo data.

Tipo	Significado
`ready`	El servidor está preparado para recibir audio
`transcript`	Texto reconocido hasta ahora. `data.is_final` marca un segmento estable
`correction`	Un segmento de transcripción refinado que reemplaza el texto anterior de ese segmento
`scribe_completed`	El audio fue aceptado y el registro se está generando. `data.status` es `processing`
`scribe_error`	La generación falló para esta sesión
`reconnect`	El servidor le pide reconectarse. `data.reason` indica por qué
`error`	Algo falló. Reintente solo cuando `data.retriable` sea verdadero
`pong`	Respuesta a su `ping`

Una correction reemplaza lo que un transcript informó para el mismo segmento. Cuando muestre texto a un médico, aplique las correcciones a medida que llegan. reconnect lleva dos motivos. server_draining significa que el servidor se está reiniciando: reconéctese y siga transmitiendo. resume_upload significa que la detención llegó antes que todo el audio: reconéctese y envíe el audio que falta.

Finalizar la sesión

Envíe este mensaje cuando termine la consulta:

{ "type": "stop_recording", "data": {} }

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 produce un registro. Si el socket simplemente se cierra sin él, el audio se conserva pero no se genera nada, ningún webhook se dispara y la consulta queda sin terminar. Envíelo siempre, incluso cuando el médico cancela.

El socket no entrega el registro médico. scribe_completed significa que la generación comenzó, no que terminó. Espere el webhook scribe_session.completed y luego obtenga el registro.

Recibir el registro

El webhook scribe_session.completed incluye consultationInternalId, el mismo consultation.id que usted envió. Obtenga el registro con él:

curl https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345/medical-record-documents \
  -H "Authorization: Bearer SU_CLAVE_API"

La finalización suele llegar dentro del minuto siguiente a stop_recording. La generación ocurre en parte mientras el audio se transmite, 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 su primera lectura devuelve una lista vacía, espere 5 segundos y vuelva a leer.

Pérdida de conexión

Reconectarse es esperado y seguro.

El socket se cae durante la grabación. Llame de nuevo a POST /v1/scribe-sessions/live con el mismo consultation.id y conéctese a la URL devuelta. El audio ya recibido se conserva.
live.url llega a expiresAt. Solicite una sesión nueva con el mismo consultation.id. Un socket ya abierto no se ve afectado.
Cierre 1013. Reintentable: el servidor está ocupado o reiniciando. Espere un momento y reconéctese.
Cierre 1003. El audio no se pudo decodificar. La sesión pasa a estado de error, así que reconectarse no la recupera. Corrija el codificador y comience una consulta nueva.
Cierre 1008. Terminal: la credencial o la sesión no son válidas. No se reconecte; reintentar devuelve el mismo resultado.

Errores

Estado	Significado
`400`	El cuerpo es inválido. `param` indica el campo
`401`	La clave API falta o es inválida
`403`	La clave API no tiene `scribe:write`, el rol `doctor`, o el vínculo con una institución
`404`	`param` `template.id`: la plantilla no existe. `param` `patient.id`: el paciente no existe. `param` `consultation.id`: ese id no está disponible para su clave
`409`	`param` `consultation.id`: el id pertenece a otra consulta, o esta ya detuvo la grabación. `param` `template.id`: la plantilla existe pero no está activa
`413`	El cuerpo JSON supera 1 MiB. Una `template.sections` en línea muy grande puede alcanzarlo. `param` es `body`
`503`	Las sesiones en vivo no están disponibles. Reintente con backoff

Consulte Errores para el envelope completo de respuesta.

Primeros pasos

Conceptos básicos

Cuentas y pacientes

Referencia

Cómo funciona

Qué debe tener la clave API

Crear una sesión

Campos de la solicitud

Elegir la plantilla

Identificar al paciente

Reintentar la misma consulta

Enviar audio

Mantener la conexión viva

Mensajes que usted recibe

Finalizar la sesión

Recibir el registro

Pérdida de conexión

Errores

​Cómo funciona

​Qué debe tener la clave API

​Crear una sesión

​Campos de la solicitud

​Elegir la plantilla

​Identificar al paciente

​Reintentar la misma consulta

​Enviar audio

​Mantener la conexión viva

​Mensajes que usted recibe

​Finalizar la sesión

​Recibir el registro

​Pérdida de conexión

​Errores

Cómo funciona

Qué debe tener la clave API

Crear una sesión

Campos de la solicitud

Elegir la plantilla

Identificar al paciente

Reintentar la misma consulta

Enviar audio

Mantener la conexión viva

Mensajes que usted recibe

Finalizar la sesión

Recibir el registro

Pérdida de conexión

Errores