Guía de integración de Agent Chats

Esta guía explica cómo usar la API de Agent Chat para listar, crear y segmentar conversaciones entre chats iniciados por el usuario y runs de AI Apps.

Casos de uso

• Construir una UI personalizada que reproduzca las pestañas "Principales" / "Apps" de la consola.
• Sincronizar el historial de conversaciones con tu propio sistema de analytics o CRM.
• Disparar y leer el resultado de un run de AI App de forma programática.

Autenticación

Todas las solicitudes requieren un JWT Bearer obtenido mediante /v1/auth/login o /v1/auth/api-key. Ver la guía de autenticación.

Enrutado de chats por origen

El campo mini_app_id de un chat decide a qué pestaña pertenece en la UI de la consola.

El mismo enfoque sirve para cualquier cliente externo que quiera mantener separados los runs de AI Apps de las conversaciones iniciadas por el usuario.

Ejemplo de extremo a extremo

1. Crear un chat vinculado a una AI App.

   curl -X POST https://api.console.solucao42.com.br/v1/agent-chats \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"mini_app_id":"65f0a1c8e1c4d23a8f5a7c00"}'

2. Listar solo chats de AI App.

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

3. Listar solo chats iniciados por el usuario, excluyendo modos especiales de "builder".

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

4. Leer los mensajes de un chat individual.

   curl "https://api.console.solucao42.com.br/v1/agent-chats/$CHAT_ID" \
     -H "Authorization: Bearer $TOKEN"

Buenas prácticas

• Envía siempre exclude_mode=mini_app_creator,monitor_builder junto con kind para evitar exponer conversaciones internas de "builder" a usuarios finales.
• Trata kind=main y kind=app como streams paginados independientes en tu UI.
• El origen de un chat es inmutable; no se pueden mover chats entre pestañas una vez creados.
• Omitir kind mantiene back-compat con integraciones existentes y devuelve ambos tipos en el mismo payload.

Manejo de errores

Escenario	HTTP	Respuesta
JWT ausente o expirado	401	{ "error": "Unauthorized" }
Falla en listado	500	{ "error_code": "AGENT_CHAT_LIST_ERROR" }
Acceso a chat de otro usuario	403	{ "error_code": "CHAT_ACCESS_DENIED" }
Chat no encontrado	404	{ "error_code": "CHAT_NOT_FOUND" }

Para detalles de schema, ver la referencia de Agent Chats API.