Chat API e integración web

Cómo se usa el endpoint de chat en CLIA: en el dashboard (Playground) y al integrar el asistente en tu propio sitio o app.

1. Dos formas de usar el endpoint de chat

Contexto	Endpoint	Autenticación	Uso
Dashboard / Playground (usuario logueado)	text `POST /chat`	text `Authorization: Bearer <JWT>`	Probar y usar el agente dentro del dashboard de CLIA (pestaña Monitor).
Integración / tu web (usuarios finales)	text `POST /public/chat`	text `x-api-key: <tu API key>`	Integrar el asistente en tu sitio o app (React, Vue, Angular, etc.).

2. Flujo dashboard (Playground)

Se usa cuando envías mensajes en la sección Monitor → Test de un agente de chat.

URL base:

text

https://clia-backend.frontiercodes.com

(o tu variable de entorno

text

NEXT_PUBLIC_BACKEND_URL

Petición:

http
POST /chat
Authorization: Bearer <access_token>
Content-Type: application/json

Cuerpo:

json
{
  "query": "Tu mensaje aquí",
  "sessionId": "session-123",
  "context": {},
  "agentId": "67558a2f8c9d1e2f3a4b5c6f"
}

Campo	Tipo	Requerido	Descripción
text `query`	string	Sí	Mensaje del usuario.
text `agentId`	string	Sí	ID del agente de chat.
text `sessionId`	string	Sí	Id estable para la conversación (ej. text `session-${Date.now()}` ).
text `context`	object	No	Contexto adicional (a menudo text `{}` ).

Respuesta (200):

json
{
  "success": true,
  "query": "Tu mensaje aquí",
  "answer": "La respuesta del asistente...",
  "source": "rag",
  "responseTime": 1250,
  "sessionId": "session-123",
  "agentId": "67558a2f8c9d1e2f3a4b5c6f",
  "tokensUsed": 150,
  "cost": 0.002
}

Códigos de error:

Código	Significado	Acción
401	Sesión expirada o token inválido	Volver a iniciar sesión.
402	Saldo insuficiente	Recargar o mejorar plan.
403	Prohibido (ej. sin suscripción al agente)	Revisar suscripción.
429	Límite de tasa (ej. 30 req/min)	Esperar y reintentar.

3. Flujo de integración (tu web o app)

Se usa cuando integras el asistente en tu propio frontend (React, Vue, Angular o cualquier stack). Llamas al backend con tu API key (creada en Dashboard → API Keys).

Petición:

http
POST /public/chat
Content-Type: application/json
x-api-key: <tu_api_key>

Cuerpo:

json
{
  "query": "Hola, ¿cómo puedes ayudarme?",
  "agentId": "67558a2f8c9d1e2f3a4b5c6f",
  "sessionId": "id_sesion_estable_opcional",
  "externalUserId": "id_tu_usuario_final",
  "context": {}
}

Campo	Tipo	Requerido	Descripción
text `query`	string	Sí	Mensaje del usuario.
text `agentId`	string	Sí	ID del agente de chat.
text `sessionId`	string	No	Mantiene el contexto de la conversación; si se omite, se genera uno.
text `externalUserId`	string	Recomendado	Id de tu usuario final para analíticas.
text `context`	object	No	Datos adicionales.

Respuesta: Misma forma que el flujo dashboard (

text

success

text

query

text

answer

text

source

text

responseTime

text

sessionId

text

agentId

, etc.).

Seguridad: Es preferible llamar a

text

/public/chat

desde tu backend (con la API key en variables de entorno) y que tu frontend llame a tu backend. Así la API key no aparece en el navegador. Consulta el Developer Hub para más guías, incluido chat embebido (proxy en backend).

4. Integrar en tu stack

Puedes integrar el asistente en cualquier stack (React, Vue, Angular, móvil, etc.) llamando al endpoint de chat desde tu app o desde tu servidor. La integración es primero API: envía

text

query

text

agentId

(y opcionalmente

text

sessionId

text

externalUserId

text

context

) y muestra el

text

answer

en tu interfaz.

Para un ejemplo de proxy en backend (recomendado en producción), consulta el Developer Hub.
Si necesitas ayuda con la implementación o consultoría, contáctanos. Podemos ofrecer orientación gratuita o implementación de pago—lo que mejor se adapte a ti.