Saltar a contenido

La API del asistente

Las rutas propias del chatbot cuelgan de /assistant. Todas exigen sesión (la de tai-api) y actúan sobre lo del usuario del token: una conversación de otro es un 404, como si no existiera.

El resto —leer las conversaciones, los mensajes, el consumo, los usuarios— es la API que genera tai-api (/chatbot/..., /auth/..., /rbac/...), con sus permisos y sus reglas. La documentación interactiva de todo está en /docs.

Con el proxy del front, todas van detrás de /api.

Conversaciones

POST /assistant/chat

Crea una conversación del usuario.

{ "title": "Averías de la L1" }

Sin title, la de asistente.titulo_nuevo_chat. Responde 201 con la conversación.

PATCH /assistant/chat/{id}

Cambia lo que venga:

{ "title": "Otro título", "visible": false, "modelo": "rapido" }
Campo
title El título
visible false la oculta y borra su memoria
modelo El alias del modelo de la conversación, que tiene que estar en el catálogo (si no, 422 en el campo modelo). null vuelve al de por defecto

PATCH /assistant/mensaje/{id}/feedback

Valora una respuesta.

{ "feedback": "bad", "feedback_comment": "La avería 12 ya estaba cerrada" }

Mensajes

POST /assistant/chat/send

Guarda el mensaje del usuario y arranca la respuesta, que llega por el WebSocket.

{ "chat_id": 42, "content": "¿Qué averías tengo abiertas?", "model": "rapido" }

model es opcional: sin él, el de la conversación, y si no, el de por defecto. Responde enseguida, sin esperar a la respuesta.

POST /assistant/chat/{id}/regenerate

Borra la respuesta al último mensaje del usuario, si la hay, y vuelve a responderlo: tras un error no hay ninguna guardada, y la de la pregunta anterior se conserva. Con ?model=<alias>, con otro modelo. Como send, es un 422 si la conversación ya está respondiendo o si el usuario tiene max_respuestas_simultaneas en curso.

POST /assistant/chat/{id}/generate-title

Le pone título a la conversación a partir de sus primeros mensajes, con el modelo de la conversación, si todavía no lo tiene, y lo devuelve. Si ya lo tiene, lo devuelve sin llamar al modelo. El front no la usa: el back pone el título solo, en paralelo con la primera respuesta, y lo manda por el WebSocket (chat_title). Sigue para los front de antes.

Informes

POST /assistant/chat/{id}/informe

{ "extension": "medio", "indicaciones": "incluye todas las tablas" }

indicaciones es opcional: en qué centrarse o qué incluir (no sale en el documento).

Empieza a preparar el informe de la conversación y responde enseguida, con un 202 y la fila de informe_conversacion en preparando. Lo demás llega por el WebSocket de la sesión: chat_report_start, y chat_report_complete (con la fila y el mensaje de sistema que lo entrega) o chat_report_error (con la fila y su error). Ver El informe de una conversación.

Pide informe_conversacion-read (403). Es un 404 si la conversación no es del usuario o asistente.informe.activo es false, y un 422 sin presupuesto, con la conversación vacía, respondiendo o preparando ya otro.

GET /assistant/informe/{id}/descarga

El documento, pintado al pedirlo, en el formato que se pida: ?formato=pdf o docx (el mismo informe sale en los dos; sin él, un 422), con Content-Disposition: attachment y un nombre como informe-ventas-de-marzo-20261026.pdf. Uno ajeno es un 404, y uno que no está listo, un 422. Leer los informes (sin descargarlos) va por el CRUD generado: includes=informes en la conversación, o messages.informes en sus mensajes.

El WebSocket

WS /assistant/ws

El de la sesión: por él llegan las respuestas de todas las conversaciones del usuario, y cada evento lleva su chat_id. Uno por pestaña. El token va en el subprotocolo tai.bearer (el cliente de tai-api lo hace con api.session.openWebSocket()), nunca en la URL.

Del cliente al servidor: {"type": "ping"}, y {"type": "assistant_response_cancelled", "chat_id": N} para parar la respuesta de una conversación (una ajena se ignora). Del servidor al cliente, los eventos de El agente.

WS /assistant/ws/chat/{id} (antiguo)

El de antes: solo las respuestas de una conversación. Sigue para los front copiados antes de /assistant/ws. Sus eventos también llevan chat_id, que un front antiguo ignora. Para parar, el mismo mensaje sin chat_id.

Cierre Motivo En
4401 Sin token o no válido los dos
4419 Token caducado los dos
4403 Origen no permitido los dos
4004 La conversación no es del usuario solo el antiguo

Consumo

GET /assistant/billing/config

El catálogo de modelos (los que tienen tarifa, y los activos sin ella marcados disponible: false), el de por defecto, el límite por defecto y si hay bolsas.

GET /assistant/billing/me

El consumo del usuario del token: su límite del mes, su consumo mes a mes y el detalle por día. ?mes=YYYY-MM para el detalle de otro mes.

GET /assistant/billing/chat/{chat_id}

Los tokens de toda una conversación, sin importes: los de sus mensajes más lo que se gastó en ella sin llegar a mensaje (el título, una respuesta cortada). Es el indicador de tokens del chat. Una conversación de otro es un 404.

Las respuestas

Todas con el sobre de tai-api:

{ "status": "success", "data": { ... }, "message": "..." }

y los errores, con su código y sus errors, como el resto de la API.