API

Todo bajo https://bot.egobytes.com/api/v1. Respuestas en JSON con la misma forma siempre: los datos en data, y los errores en error con un codigo estable que tu programa puede comparar.

Las dos claves

Hay dos credenciales porque hay dos mundos, y mezclarlos es el error caro.

Clave	Dónde vive	Qué puede
`pk_…`	En el HTML de tu sitio. Es pública.	Solo conversar. La protege la lista de dominios del widget, no el secreto.
`egb_live_…`	En tu servidor. Nunca en un navegador.	Cargar la base de conocimiento y leer conversaciones, leads y consumo.

La clave privada se muestra una sola vez. Se guarda cifrada: si se pierde no se recupera, se revoca y se emite otra desde el panel.

Cargar la base de conocimiento

Es la parte que hace bueno al bot. Se manda con la clave privada en Authorization: Bearer.

POST /knowledge/documents

Alta o actualización. Es upsert por external_id: mandás el id que usás en tu sistema y, cuando el texto cambia, lo volvés a mandar con el mismo id.

curl -X POST https://bot.egobytes.com/api/v1/knowledge/documents \
  -H "Authorization: Bearer egb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "servicio:soporte",
    "titulo": "Horario de soporte",
    "contenido": "Atendemos de lunes a viernes de 9 a 19...",
    "tipo": "ficha",
    "prioridad": 10
  }'

Campo	Qué es
external_id	Tu id. Es lo que evita duplicados en cada sincronización.
titulo	Cómo se llama. Entra en cada fragmento, así que ayuda a encontrarlo.
contenido	El texto. Se corta solo en fragmentos buscables.
tipo	`ficha` viaja entero en cada respuesta; cualquier otro valor se busca.
prioridad	1 a 10. Desempata cuando dos documentos compiten en la búsqueda.
url	Opcional. Para que el bot pueda citar de dónde salió.

Cuidado con tipo: "ficha". Eso viaja completo en cada mensaje: sirve para media docena de cosas críticas y encarece cada conversación si se usa para cincuenta.

POST /knowledge/documents/bulk

Hasta 200 de una, en documentos. Un documento mal armado no corta el lote: la respuesta trae meta.guardados y la lista de errores con su índice.

El resto

GET /knowledge/documents	Lo que hay cargado, con filtros.
DELETE /knowledge/documents/{external_id}	Baja.
POST /knowledge/reindex	Vuelve a cortar todo.
GET /knowledge/summary	Cuántos documentos y fragmentos hay.

Leer lo que pasó

GET /conversations	Filtros por fecha, variante, estado y `sin_respuesta`.
GET /conversations/{id}	La charla completa con su lead.
GET /leads	Los contactos capturados, con lo que el bot dedujo.
GET /usage	Tokens, costo y conversaciones por día, más el estado del presupuesto.

Conversar (clave pública)

Esto es lo que hace el widget. Solo hace falta si querés construir tu propia pantalla.

# 1. Abrir la conversación
curl -X POST https://bot.egobytes.com/api/v1/chat/sessions \
  -H "X-Ego-Key: pk_..." -H "Content-Type: application/json" \
  -d '{"pagina":"https://tusitio.com/precios"}'

# 2. Mandar un mensaje (respuesta completa)
curl -X POST https://bot.egobytes.com/api/v1/chat/sessions/{id}/messages \
  -H "X-Ego-Key: pk_..." -H "Content-Type: application/json" \
  -d '{"texto":"¿cuánto cuesta?"}'

# 3. O por streaming, palabra por palabra (SSE)
curl -N "https://bot.egobytes.com/api/v1/chat/sessions/{id}/stream?clave=pk_...&m=hola"

El stream manda eventos texto con cada pedazo y termina con un evento fin. Si el mensaje choca con un límite, fin trae el corte que lo explica.

Contactos desde tu sitio (clave pública)

El formulario de contacto de tu sitio puede crear contactos directo en tu bandeja, con aviso en el teléfono y seguimiento. Usa la misma clave pública que el widget y solo funciona desde los dominios que tenés cargados. Dejá el campo sitio_web vacío y escondido: es la trampa para los programas de spam.

# Con fetch, desde tu página
fetch('https://bot.egobytes.com/api/v1/leads', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Ego-Key': 'pk_...' },
  body: JSON.stringify({ nombre: 'Marta', telefono: '8675 1245', correo: '[email protected]', mensaje: 'Quiero cotizar' })
})

# O con un formulario común: vuelve a `volver` (tiene que ser de tu dominio)
<form action="https://bot.egobytes.com/api/v1/leads" method="post">
  <input type="hidden" name="clave" value="pk_...">
  <input type="hidden" name="volver" value="https://tusitio.com/gracias">
  <input name="nombre"> <input name="telefono"> <input name="correo"> <textarea name="mensaje"></textarea>
</form>

Errores

Siempre con el mismo cuerpo. Compará el codigo, nunca el texto.

{
  "error": {
    "codigo": "limite_conversacion",
    "mensaje": "Llegamos al límite de esta charla..."
  }
}

Código	Qué pasó
clave_faltante · clave_invalida	No vino la clave, o no existe.
dominio	La clave pública se usó desde un sitio que no está en la lista.
turnstile	No se pudo verificar que del otro lado hay una persona.
largo	El mensaje pasa del máximo configurado.
limite_conversacion · limite_ip · limite_sesiones	Se alcanzó un freno de uso.
presupuesto	La cuenta llegó a su tope mensual de gasto.
pais	El país está en la lista bloqueada de la cuenta.

El widget

<script src="https://bot.egobytes.com/w.js"
        data-key="pk_tu_clave"
        data-label="Preguntame lo que sea"
        data-color="#9a6bff"
        data-side="derecha"
        data-open-after="8"
        data-open-on="/lp,/promo"
        defer></script>

Atributo	Para qué
data-key	Obligatorio. La clave pública del widget.
data-label	El texto del botón.
data-color	El color del botón.
data-side	`derecha` o `izquierda`.
data-open-after	Segundos hasta abrirse solo. Sin el atributo, no se abre solo.
data-open-on	Rutas donde vale esa apertura automática.

¿Algo no está acá? Escribinos — o preguntale al bot de la portada, que también sabe de esto.