Horneross - Automatización de Operaciones

POST

api

agent

{agentId}

chat

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"
    }
  }'

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',
    },
    body: JSON.stringify({
      query: '¿Cuáles son los horarios de atención?',
      conversationId: 'conv_usuario_123',
      contact: {
        email: 'cliente@ejemplo.com',
        firstName: 'María'
      }
    }),
  }
);

const data = await response.json();
console.log(data.answer);

import requests

response = requests.post(
    'https://app.horneross.com/api/v2/agent/ag_abc123/chat',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'query': '¿Cuáles son los horarios de atención?',
        'conversationId': 'conv_usuario_123',
        'contact': {
            'email': 'cliente@ejemplo.com',
            'firstName': 'María'
        }
    }
)

data = response.json()
print(data['answer'])

{
  "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
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key inválida o expirada"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agente no encontrado"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Demasiadas requests. Intentá de nuevo en 60 segundos.",
    "retryAfter": 60
  }
}

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

string

required

ID único del agente. Lo encontrás en el dashboard o en la URL del agente.

Headers

string

required

Bearer token con tu API key. Formato: Bearer sk_live_xxx

string

required

Siempre application/json

string

Usar text/event-stream para respuestas en streaming

Request Body

string

required

Mensaje del usuario a enviar al agente.

string

required

ID de la conversación. Usá el mismo ID para mantener el contexto entre mensajes.

string

ID único del visitante/usuario. Requerido para agentes públicos.

boolean

default:"false"

Si es true, la respuesta se envía token por token via Server-Sent Events (SSE).

string

default:"api"

Canal de origen del mensaje. Valores: api, website, whatsapp, widget, dashboard

object

Datos del contacto para CRM.

Show Propiedades de contact

string

Email del contacto

string

Nombre del contacto

string

Apellido del contacto

string

Teléfono con código de país (ej: +5491123456789)

object

Campos personalizados en formato key-value

object

Filtros para limitar la búsqueda en datastores.

Show Propiedades de filters

string[]

Array de IDs de datasources específicos donde buscar

array

Archivos adjuntos al mensaje.

Show Propiedades de attachment

string

required

URL del archivo adjunto

string

Nombre del archivo

string

MIME type del archivo (ej: application/pdf, image/png)

number

Tamaño en bytes

string

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"
    }
  }'

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',
    },
    body: JSON.stringify({
      query: '¿Cuáles son los horarios de atención?',
      conversationId: 'conv_usuario_123',
      contact: {
        email: 'cliente@ejemplo.com',
        firstName: 'María'
      }
    }),
  }
);

const data = await response.json();
console.log(data.answer);

import requests

response = requests.post(
    'https://app.horneross.com/api/v2/agent/ag_abc123/chat',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'query': '¿Cuáles son los horarios de atención?',
        'conversationId': 'conv_usuario_123',
        'contact': {
            'email': 'cliente@ejemplo.com',
            'firstName': 'María'
        }
    }
)

data = response.json()
print(data['answer'])

Response

string

required

Respuesta generada por el agente.

string

required

ID de la conversación (mismo que enviaste o uno nuevo si no existía).

string

required

ID único del mensaje generado.

array

Fuentes de conocimiento utilizadas para generar la respuesta.

Show Propiedades de source

string

Nombre o URL de la fuente

number

Score de relevancia (0-1)

string

Nombre del datasource de origen

string

Fragmento de texto utilizado

object

Métricas de uso de tokens.

Show Propiedades de usage

number

Tokens usados en el prompt

number

Tokens generados en la respuesta

number

Total de tokens consumidos

object

Información adicional sobre la respuesta.

Show Propiedades de metadata

string

Modelo utilizado (ej: gpt-4o)

number

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
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key inválida o expirada"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agente no encontrado"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Demasiadas requests. Intentá de nuevo en 60 segundos.",
    "retryAfter": 60
  }
}

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;
      }
    }
  }
}

import requests
import json

response = requests.post(
    'https://app.horneross.com/api/v2/agent/ag_abc123/chat',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
        'Accept': 'text/event-stream',
    },
    json={
        'query': 'Contame sobre tus productos',
        'conversationId': 'conv_123',
        'streaming': True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data = json.loads(line[6:])
            if data['type'] == 'token':
                print(data['value'], end='', flush=True)
            elif data['type'] == 'done':
                print('\n--- Respuesta completa ---')

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"
  }'

const response = await fetch(
  'https://app.horneross.com/api/v2/agent/ag_public123/chat',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'Hola, necesito ayuda',
      conversationId: 'conv_visitor_abc',
      visitorId: 'visitor_unique_id',
    }),
  }
);

Listar conversaciones del agente

GET /api/v2/agent/{agentId}/conversations

string

Filtrar por visitante. Requerido para agentes públicos.

number

default:"10"

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

Tasks APICrear y gestionar tareas automáticas para tus agentes.

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"
    }
  }'

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',
    },
    body: JSON.stringify({
      query: '¿Cuáles son los horarios de atención?',
      conversationId: 'conv_usuario_123',
      contact: {
        email: 'cliente@ejemplo.com',
        firstName: 'María'
      }
    }),
  }
);

const data = await response.json();
console.log(data.answer);

import requests

response = requests.post(
    'https://app.horneross.com/api/v2/agent/ag_abc123/chat',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'query': '¿Cuáles son los horarios de atención?',
        'conversationId': 'conv_usuario_123',
        'contact': {
            'email': 'cliente@ejemplo.com',
            'firstName': 'María'
        }
    }
)

data = response.json()
print(data['answer'])

{
  "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
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key inválida o expirada"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agente no encontrado"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Demasiadas requests. Intentá de nuevo en 60 segundos.",
    "retryAfter": 60
  }
}

Empezar

Guías

Industrias

Developers

Soporte

Legal

Chat API

Endpoint

Autenticación

Path Parameters

Headers

Request Body

Response

Streaming (SSE)

Eventos SSE

Agentes públicos (sin API key)

Listar conversaciones del agente

Errores comunes

​Endpoint

​Autenticación

​Path Parameters

​Headers

​Request Body

​Response

​Streaming (SSE)

​Eventos SSE

​Agentes públicos (sin API key)

​Listar conversaciones del agente

​Errores comunes

Endpoint

Autenticación

Path Parameters

Headers

Request Body

Response

Streaming (SSE)

Eventos SSE

Agentes públicos (sin API key)

Listar conversaciones del agente

Errores comunes