El endpoint de Chat es la forma principal de interactuar con tus agentes programáticamente.
Endpoint
POST /api/v2/agent/{agentId}/chat
Autenticación
| Tipo de agente | Autenticación requerida |
|---|
| Agente privado | Authorization: Bearer API_KEY |
| Agente público | Solo visitorId en el body |
Path Parameters
ID único del agente. Lo encontrás en el dashboard o en la URL del agente.
Bearer token con tu API key. Formato: Bearer sk_live_xxx
Usar text/event-stream para respuestas en streaming
Request Body
Mensaje del usuario a enviar al agente.
ID de la conversación. Usá el mismo ID para mantener el contexto entre mensajes.
ID único del visitante/usuario. Requerido para agentes públicos.
Si es true, la respuesta se envía token por token via Server-Sent Events (SSE).
Canal de origen del mensaje. Valores: api, website, whatsapp, widget, dashboard
Datos del contacto para CRM.Show Propiedades de contact
Teléfono con código de país (ej: +5491123456789)
Campos personalizados en formato key-value
Filtros para limitar la búsqueda en datastores.Show Propiedades de filters
Array de IDs de datasources específicos donde buscar
Archivos adjuntos al mensaje.Show Propiedades de attachment
MIME type del archivo (ej: application/pdf, image/png)
Override del modelo a usar. Valores: gpt-4o, gpt-4o-mini, claude-3-5-sonnet, gemini-1-5-pro
curl -X POST https://app.horneross.com/api/v2/agent/ag_abc123/chat \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"query": "¿Cuáles son los horarios de atención?",
"conversationId": "conv_usuario_123",
"contact": {
"email": "cliente@ejemplo.com",
"firstName": "María"
}
}'
Response
Respuesta generada por el agente.
ID de la conversación (mismo que enviaste o uno nuevo si no existía).
ID único del mensaje generado.
Fuentes de conocimiento utilizadas para generar la respuesta.Show Propiedades de source
Nombre o URL de la fuente
Score de relevancia (0-1)
Nombre del datasource de origen
Fragmento de texto utilizado
Métricas de uso de tokens.Show Propiedades de usage
Tokens usados en el prompt
Tokens generados en la respuesta
Total de tokens consumidos
Información adicional sobre la respuesta.Show Propiedades de metadata
Modelo utilizado (ej: gpt-4o)
Tiempo de respuesta en milisegundos
{
"answer": "Nuestros horarios de atención son de lunes a viernes de 9:00 a 18:00 horas.",
"conversationId": "conv_usuario_123",
"messageId": "msg_xyz789",
"sources": [
{
"source": "FAQ - Horarios",
"score": 0.95,
"datasourceName": "Preguntas Frecuentes",
"chunk": "Los horarios de atención al público son de lunes a viernes..."
}
],
"usage": {
"promptTokens": 245,
"completionTokens": 67,
"totalTokens": 312
},
"metadata": {
"model": "gpt-4o",
"latency": 1234
}
}
Streaming (SSE)
Para recibir la respuesta token por token en tiempo real, usá streaming: true:
const response = await fetch(
'https://app.horneross.com/api/v2/agent/ag_abc123/chat',
{
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_xxx',
'Content-Type': 'application/json',
'Accept': 'text/event-stream',
},
body: JSON.stringify({
query: 'Contame sobre tus productos',
conversationId: 'conv_123',
streaming: true
}),
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n');
for (const line of lines) {
if (line.startsWith('data: ')) {
const data = JSON.parse(line.slice(6));
switch (data.type) {
case 'token':
process.stdout.write(data.value);
break;
case 'source':
console.log('Fuente:', data.source);
break;
case 'done':
console.log('\n--- Respuesta completa ---');
break;
}
}
}
}
Eventos SSE
| Evento | Descripción |
|---|
token | Cada token de la respuesta |
source | Fuente de conocimiento encontrada |
tool_call | Herramienta ejecutada por el agente |
done | Respuesta completada |
error | Error durante el procesamiento |
Agentes públicos (sin API key)
Para agentes con visibilidad pública, no necesitás API key pero sí visitorId:
curl -X POST https://app.horneross.com/api/v2/agent/ag_public123/chat \
-H "Content-Type: application/json" \
-d '{
"query": "Hola, necesito ayuda",
"conversationId": "conv_visitor_abc",
"visitorId": "visitor_unique_id"
}'
Listar conversaciones del agente
GET /api/v2/agent/{agentId}/conversations
Filtrar por visitante. Requerido para agentes públicos.
Cantidad de resultados. Máximo 50.
{
"conversations": [
{
"id": "conv_abc123",
"createdAt": "2024-01-21T10:00:00Z",
"messagesCount": 5,
"lastMessage": "Gracias por la ayuda",
"status": "resolved"
}
]
}
Errores comunes
| Código | Error | Causa | Solución |
|---|
401 | UNAUTHORIZED | API key inválida | Verificá tu API key en Settings → API Keys |
404 | NOT_FOUND | Agent ID incorrecto | Verificá el agentId en la URL del agente |
400 | BAD_REQUEST | Falta query o conversationId | Incluí los campos requeridos |
429 | RATE_LIMIT_EXCEEDED | Rate limit excedido | Esperá el tiempo indicado en retryAfter |
500 | INTERNAL_ERROR | Error del servidor | Reintentá en unos segundos |
