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.
Sin title, la de asistente.titulo_nuevo_chat. Responde 201 con la conversación.
PATCH /assistant/chat/{id}¶
Cambia lo que venga:
| 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.
Mensajes¶
POST /assistant/chat/send¶
Guarda el mensaje del usuario y arranca la respuesta, que llega por el WebSocket.
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¶
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:
y los errores, con su código y sus errors, como el resto de la API.