Poné tu artefacto adentro de agentia

curl -X POST https://www.chayana.co/api/complementos/verificar \
  -H "Authorization: Bearer agc_tu_token" \
  -H "content-type: application/json" \
  -d '{"version":"1.0.0"}'

El cuerpo es opcional. Si mandás version la registramos, y es lo que nos permite dejar de soportar versiones viejas sin romperle el día a nadie. Si no la mandás y el cliente tiene una versión mínima configurada, no te habilitamos.

{
  "codigo": 1,
  "estado": "habilitado",
  "descripcion": "Habilitado.",
  "puede_atender": true,
  "modo": "completo",
  "mensaje_para_el_usuario": null,
  "vence": "2026-08-28T04:31:24.991Z",
  "emitida": "2026-08-27T04:31:24.991Z",
  "complemento": { "clave": "cotizador_piletas", "nombre": "Cotizador" },
  "cliente": { "nombre": "AquaFibra", "agente": "Jordan" },
  "uso": { "sesiones_del_mes": 12, "sesiones_incluidas": null },
  "reportar_en": "https://www.chayana.co/api/complementos/reportar",
  "firma": "K7x..."
}

Siempre devolvemos 200 cuando la credencial es válida, aunque el cliente no pueda atender. El resultado está en el cuerpo, no en el estado HTTP: muchos clientes de HTTP tiran excepción ante un 402 o un 403 antes de que llegues a leer el motivo y el mensaje para la persona. El 401 sí es un 401: significa que no te reconocemos.

codigo|estado|puede_atender|modo|vence|emitida

1|habilitado|1|completo|2026-08-28T04:31:24.991Z|2026-08-27T04:31:24.991Z

import { createHmac, timingSafeEqual } from "node:crypto";

function firmaValida(l, token) {
  const mensaje = [
    l.codigo, l.estado, l.puede_atender ? 1 : 0, l.modo, l.vence, l.emitida,
  ].join("|");

  const esperada = createHmac("sha256", token).update(mensaje).digest("base64url");
  const a = Buffer.from(esperada);
  const b = Buffer.from(l.firma ?? "");

  return a.length === b.length && timingSafeEqual(a, b);
}

import base64, hmac, hashlib

def firma_valida(l, token):
    mensaje = "|".join([
        str(l["codigo"]), l["estado"], "1" if l["puede_atender"] else "0",
        l["modo"], l["vence"], l["emitida"],
    ])

    esperada = base64.urlsafe_b64encode(
        hmac.new(token.encode(), mensaje.encode(), hashlib.sha256).digest()
    ).rstrip(b"=").decode()

    return hmac.compare_digest(esperada, l.get("firma", ""))

Ojo con el base64url: va sin relleno. En Python hay que sacar los = del final, que es donde se tropieza todo el mundo.

curl -X POST https://www.chayana.co/api/complementos/reportar \
  -H "Authorization: Bearer agc_tu_token" \
  -H "content-type: application/json" \
  -d '{
    "version": "1.0.0",
    "sesiones": [
      {
        "id": "wa-5491122334455-1782",
        "inicio": "2026-08-27T10:00:00Z",
        "fin": "2026-08-27T10:06:31Z",
        "paso": "precio",
        "desenlace": "cotizado",
        "contacto": "Marta",
        "detalle": { "modelo": "8x4", "metros": 32 }
      }
    ]
  }'

{ "recibidas": 1, "guardadas": 1, "descartadas": 0 }

Hasta 500 sesiones por lote. Podés mandarlas de a una al cerrar cada sesión, o juntar y mandar cada tanto: nos da igual. Una sesión sin fecha de inicio legible se descarta sola, sin tirar el lote entero, y te lo decimos en descartadas.

Una sesión sin fin se cuenta como abierta. Podés reportarla al empezar y volver a mandarla completa después, con el mismo id: la segunda pisa a la primera.

curl -X POST https://www.chayana.co/api/complementos/conversar \
  -H "Authorization: Bearer agc_tu_token" \
  -H "content-type: application/json" \
  -d '{
    "sesion_id": "5491122334455",
    "mensaje": "¿la lona de la 8x4 aguanta granizo?",
    "contacto": "Marta",
    "conversacion": [
      { "quien": "persona", "texto": "Hola, quiero una pileta" },
      { "quien": "complemento", "texto": "¡Hola! ¿Qué modelo tenés en mente?" },
      { "quien": "persona", "texto": "La 8x4" },
      { "quien": "complemento", "texto": "Son 32 m2. Te queda en USD 4.200." }
    ],
    "contexto": "Total cotizado 4200. Presupuesto interno #8812."
  }'

{
  "atendido": true,
  "codigo": 1,
  "estado": "atendido",
  "respuesta": "Sí, la lona reforzada que usamos está probada para granizo...",
  "conversacion_id": "8f3c...",
  "costo_usd": 0.0142
}

conversacion es la charla que venías teniendo, tal cual ocurrió de tu lado. Es lo que hace que el agente entre sabiendo: si la persona ya eligió, dio medidas y recibió un precio, tiene que leer eso y no un resumen de dos líneas. Se siembra una sola vez, en el primer traspaso de esa sesión, así que podés mandarla completa en cada llamada —que es lo más fácil de programar— sin que se duplique nada.

contexto es otra cosa: lo que sabés y no se dijo en la charla —un total, un id interno, el nombre del vendedor—. Va a las instrucciones del turno y no al historial, así que no le ensucia al cliente la conversación que después lee. Mandalo en cada llamada si cambia.

Cuando no se pudo, atendido viene en false con el motivo en estado: agente_no_operativo si el cliente todavía no puso su agente en producción, sin_comportamiento si no tiene uno publicado, el_motor_fallo si falló de nuestro lado. Y si el complemento no está habilitado, contesta lo mismo que la verificación, con mensaje_para_el_usuario listo para relevar. Sigue siendo 200: el motivo lo tenés que poder leer.

La charla queda del lado de agentia, en la misma pantalla de conversaciones que el resto y marcada como llegada por un complemento. Ese es el punto: el cliente tiene un solo lugar donde mirar. El consumo de tokens va a su cuenta, no a la tuya, porque es su agente el que trabaja.

Tarda lo que tarda un modelo en contestar, así que no la llames con un timeout de dos segundos. Y si te contesta que no atendió, seguí vos: es tu conversación.

{
  "evento": "derivacion",
  "sesion_id": "wa-5491122334455-1782",
  "conversacion_id": "8f3c...",
  "contacto": "Marta",
  "canal": "whatsapp",
  "motivo": "Quiere cotizar una pileta",
  "resumen": "Preguntó por modelos y precios de piletas de fibra.",
  "emitida": "2026-08-27T21:14:02.318Z"
}

El sesion_id te dice de quién se trata. Si la conversación había empezado de tu lado, es el id que ya usás para reportar y para consultarnos. Si empezó del nuestro, es el identificador de la persona en el canal por donde escribió: en WhatsApp, su número. No es un id para reportar. Cuando la derivación trae canal, la clave del hilo es conversacion_id: reportá y consultá esa sesión con un id tuyo derivado de él, el mismo en /reportar y en /conversar.

Viene firmado en la cabecera x-agentia-firma: es el HMAC-SHA256 del cuerpo entero, tal cual lo recibiste, con tu token como clave y en base64url. Comprobalo antes de hacer nada. Sin eso, cualquiera que descubra tu dirección puede empujarte conversaciones inventadas.

const firma = req.headers["x-agentia-firma"];
const esperada = createHmac("sha256", TOKEN)
  .update(cuerpoCrudo)          // el texto sin parsear, no el objeto
  .digest("base64url");

if (firma !== esperada) return res.status(401).end();

Contestá 2xx si la tomás. Si contestás un error, o si tardás más de ocho segundos, el agente se queda atendiendo él y le avisa a la persona: preferimos eso antes que dejarla sin nadie del otro lado.

Con canal, podés contestar la derivación con { "responder": "..." } para saludar: sale por el canal justo después del mensaje del agente que le avisa a la persona que la pasa. Es mejor que un /enviar inmediato, que puede llegar antes que ese aviso.

{
  "evento": "mensaje",
  "conversacion_id": "8f3c...",
  "canal": "whatsapp",
  "contacto": { "id": "5493875550000", "nombre": "Marta" },
  "mensaje": "Hola, quiero cotizar una pileta",
  "origen": {
    "anuncioId": "120226305854810726",
    "tipo": "ad",
    "titular": "Cotizá tu pileta",
    "clicId": "Aff-n8ZTODiE79d22KtAwQKj9e"
  }
}

origen viene sólo en el primer mensaje, que es el que dispara el anuncio. Los siguientes llegan sin eso, así que si lo necesitás, guardalo.

{ "responder": "Dale, ¿de qué medida la querés?" }

Lo mandamos nosotros por el número del cliente. Tenés 8 segundos: si vas a tardar más —cotizar, consultar un sistema— contestá { "recibido": true } y usá la llamada de abajo cuando tengas la respuesta.

curl -X POST https://www.chayana.co/api/complementos/enviar \
  -H "Authorization: Bearer agc_tu_token" \
  -H "content-type: application/json" \
  -d '{
    "conversacion_id": "8f3c...",
    "mensaje": "Te queda USD 12.400, incluye instalación."
  }'

Sólo en conversaciones que tengas tomadas. El mensaje sale a nombre del negocio del cliente, así que sin esa comprobación tu token serviría para escribirle a cualquier contacto suyo. Hay tope por hora: un bucle mal escrito son miles de mensajes desde un número que no es tuyo, y al que le bajan la calificación es al cliente.

curl -X POST https://www.chayana.co/api/complementos/asignar \
  -H "Authorization: Bearer agc_tu_token" \
  -H "content-type: application/json" \
  -d '{
    "conversacion_id": "8f3c...",
    "contexto": "Cotizó 8x4, quiere hablar de financiación"
  }'

Desde ahí contesta el agente, con toda la charla adelante: lo que contestaste vos ya quedó guardado, no hace falta que mandes el historial. En contexto va lo que sabés y no está dicho en la charla.

Es una sola dirección. Después de esto, /enviar sobre esa conversación devuelve 409. Si el agente necesita volver a pasártela, tiene su propia herramienta para derivar.

{ "conversacion_id": "8f3c..." }

→ 200 { "escribiendo": true }

Mismas reglas que /enviar: solo en conversaciones que atendés (409 si no), 403 si la licencia no te habilita. Si el canal no tiene indicador —el correo, por ejemplo—, contesta 200 con escribiendo: false: no es un error. Hay un tope de 600 por hora por instalación. No lo llames si no vas a contestar.

{
  "conversacion_id": "8f3c...",
  "mensaje": "¿Cómo podemos ayudarte?",
  "opciones": {
    "items": [
      { "id": "pileta", "titulo": "Quiero una pileta" },
      { "id": "ayuda",  "titulo": "Necesito ayuda" }
    ]
  }
}

• tipo es botones o lista. Si falta, hasta 3 van como botones y de 4 a 10 como lista.
• Botones: de 1 a 3, título hasta 20 caracteres, mensaje hasta 1024. No llevan descripción.
• Lista: de 1 a 10, título hasta 24, descripción hasta 72, boton hasta 20 (por defecto "Ver opciones"), mensaje hasta 4096.
• El id va hasta 200 caracteres. Ni los ids ni los títulos se repiten.
• Solo con botones, una imagen arriba: "encabezado": { "imagen": "https://..." }. Con lista es un 400. Si la imagen no baja o el canal no la muestra, los botones salen sin ella; en /enviar te contestamos "encabezado": false.

No recortamos nada: dos títulos recortados pueden quedar iguales. En /enviar, lo que no cumple es un 400 que dice qué campo y por qué. En la respuesta de un aviso no tenés cómo enterarte de un error, así que ahí —y también si el canal no muestra botones o si WhatsApp los rechaza— mandamos el texto con las opciones numeradas desde 1, en el orden de items. La persona nunca se queda sin la pregunta.

{
  "evento": "mensaje",
  "conversacion_id": "8f3c...",
  "mensaje": "Quiero una pileta",
  "respuesta": { "id": "pileta", "titulo": "Quiero una pileta" }
}

mensaje sigue trayendo el título, para el que no lee respuesta. respuesta es nulo cuando la persona escribió en vez de tocar, y si toca un botón de un mensaje viejo te llega igual con su id.

{
  "conversacion_id": "8f3c...",
  "mensaje": "Tu presupuesto AF-20260910-ABC123. Válido por 15 días.",
  "documento": {
    "url": "https://tu-servidor/presupuestos/AF-20260910-ABC123.pdf?firma=...",
    "nombre": "Presupuesto AF-20260910-ABC123.pdf"
  }
}

Lo bajamos al recibir el pedido, lo validamos y lo guardamos: a WhatsApp le pasamos un link nuestro de corta vida, nunca el tuyo, y el cliente lo puede abrir desde su pantalla. La dirección tiene que ser https y no puede apuntar a una red privada; no seguimos redirecciones; tiene que responder en diez segundos, pesar hasta 5 MB, ser application/pdf y empezar con %PDF. El mensaje va como pie, hasta 1024. No va junto con opciones.

{
  "conversacion_id": "8f3c...",
  "mensaje": "Rectangular: la que mejor aprovecha patios angostos.",
  "imagen": { "url": "https://tu-servidor/modelos/rectangular.png" }
}

Las mismas reglas que el PDF, pero tiene que ser image/png o image/jpeg y empezar como tal. El mensaje va como pie, hasta 1024. No va junto con opciones ni con documento.

Si el documento o la imagen no se pudo, contestamos 422 con el motivo —direccion_no_permitida, no_se_pudo_bajar, no_es_pdf, no_es_imagen, muy_grande, el_canal_no_admite_documentos o el_canal_no_admite_imagenes— y no sale nada: mandá el texto solo.

Cada mensaje con opciones, documento o imagen cuenta como uno para el tope por hora. Lo que se mostró, lo que se eligió, el documento y la imagen quedan en la conversación: el cliente los ve en su pantalla, y el agente los tiene en su historial cuando le devolvés la charla.