API de Agent Chats

Endpoints para listar, crear, leer, actualizar y eliminar conversaciones del Agent Chat. El endpoint de listado admite el parámetro kind para separar las conversaciones iniciadas por el usuario de las generadas por ejecuciones de AI Apps.

Listar Agent Chats

Devuelve una lista paginada de los chats del usuario actual.

GET/v1/agent-chats

Permiso requerido: usuario autenticado (no requiere acción IAM adicional para leer chats propios).

Parámetros de consulta:

Parámetro	Tipo	Default	Descripción
page	integer	1	Número de página, comienza en 1.
per_page	integer	20	Items por página (máx 100).
exclude_mode	string	—	Lista separada por comas de modos a excluir (p. ej. mini_app_creator,monitor_builder).
kind	string	—	Filtra por origen del chat. main devuelve chats iniciados por el usuario (web o WhatsApp); app devuelve chats creados por ejecuciones de AI Apps. Omitir para el comportamiento por defecto (devuelve ambos).

Cuando kind se omite o no es válido, el endpoint se comporta exactamente como en versiones anteriores (back-compat).

Ejemplo — solo chats principales:

curl "https://api.console.solucao42.com.br/v1/agent-chats?kind=main&exclude_mode=mini_app_creator,monitor_builder" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ejemplo — solo runs de AI Apps:

curl "https://api.console.solucao42.com.br/v1/agent-chats?kind=app" \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 200 OK

{
  "total": 42,
  "quantity": 20,
  "records": [
    {
      "id": "65f0a1c8e1c4d23a8f5a7b30",
      "user_id": "65f0a1c8e1c4d23a8f5a7b00",
      "title": "Ventas por región",
      "channel": "web",
      "is_special": false,
      "message_count": 6,
      "created_at": "2026-05-01T13:42:00.000Z",
      "updated_at": "2026-05-02T08:10:00.000Z",
      "mode": "default",
      "mini_app_id": null
    }
  ]
}

La respuesta del listado se ordena por updated_at descendente. Los chats de WhatsApp aparecen en el mismo payload que los chats web; los clientes pueden separarlos en la UI revisando el campo channel.

Errores:

Status	Error Code	Descripción
401	UNAUTHORIZED	JWT ausente o inválido.
500	AGENT_CHAT_LIST_ERROR	Falla interna al listar chats.

Obtener Agent Chat

Devuelve un único chat con sus mensajes visibles.

GET/v1/agent-chats/{chatId}

Permiso requerido: usuario autenticado, y el chat debe pertenecer al solicitante.

Parámetros de consulta:

Parámetro	Tipo	Descripción
messages_after	fecha ISO	Cuando se proporciona, devuelve solo mensajes posteriores a este timestamp (sync incremental).

Errores:

Status	Error Code	Descripción
403	CHAT_ACCESS_DENIED	El chat pertenece a otro usuario.
404	CHAT_NOT_FOUND	El ID del chat no existe.

Crear Agent Chat

Crea un nuevo agent chat.

POST/v1/agent-chats

Permiso requerido: visualizations:execute.

Body:

{
  "title": "Título opcional",
  "mini_app_id": "65f0a1c8e1c4d23a8f5a7c00"
}

Campo	Tipo	Descripción
title	string (opcional)	Título personalizado para la conversación.
mini_app_id	string (opcional)	Cuando se proporciona, vincula el chat a una ejecución de AI App. El chat aparecerá entonces en los listados con kind=app.

Respuesta: 201 Created con el chat creado.

Errores:

Status	Error Code	Descripción
403	—	Permiso visualizations:execute denegado.
422	—	Validación de schema falló.
500	AGENT_CHAT_CREATE_ERROR	Falla interna al crear chat.

Actualizar Título

PUT/v1/agent-chats/{chatId}

Body: { "title": "Nuevo título" }. Devuelve el chat actualizado.

Eliminar Chat

DELETE/v1/agent-chats/{chatId}

Soft-delete del chat. Las llamadas posteriores a list no lo incluirán.

Notas sobre kind

• kind=main: solo chats cuyo mini_app_id es null (chats web y de WhatsApp).
• kind=app: solo chats con mini_app_id definido (chats creados por ejecuciones de AI Apps).
• Omitido: devuelve ambos tipos, preservando el comportamiento anterior.
• kind y exclude_mode se combinan: ?kind=main&exclude_mode=mini_app_creator,monitor_builder es la consulta típica que la consola web usa para poblar la pestaña "Principales".