Poné tu artefacto adentro de Chayana

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": 5,
  "estado": "fuera_de_horario",
  "descripcion": "Fuera del horario de atención.",
  "puede_atender": false,
  "modo": "completo",
  "mensaje_para_el_usuario": "Hoy ya cerramos. Te respondemos mañana a las 9.",
  "vence": "2026-08-28T12:00:00.000Z",
  "emitida": "2026-08-27T21:14:02.318Z",
  "firma": "K7x..."
}

Mirá el vence: una licencia de fuera de horario vence cuando el negocio vuelve a abrir, no al día siguiente. Guardala como cualquier otra y vas a estar preguntando de nuevo justo cuando abren.

Mostrale a la persona mensaje_para_el_usuario tal cual: lo escribió el cliente y dice cuándo vuelve. No inventes el tuyo.

Es una razón más para las dos reglas de siempre. Una: no guardes un «sí» para siempre, porque el horario se cierra solo y tu licencia vence justo para que lo notes. Dos: ramificá sobre puede_atender y no sobre el código, porque fuera de horario llega con el mismo 5 que cualquier otro motivo y lo que te importa es que hoy no atendés.

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 $ 6.900.000." }
    ],
    "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...",
  "derivada": false,
  "costo_usd": 0.0142
}

derivada viene en true cuando, en ese turno, el agente te devolvió la conversación porque lo que pide la persona es lo que vos sabés hacer. Retomá tu proceso: por acá no hay canal por donde tomar el hilo, así que es la forma de enterarte. Si tu contrato dice que abrís vos, respuesta viene nula: el agente no habla, igual que por un canal, donde su texto no sale.

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 Chayana, 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.",
  "datos": {
    "nombre": "Marta Gómez",
    "localidad": "Villa Allende",
    "modelo": "AF03"
  },
  "emitida": "2026-08-27T21:14:02.318Z"
}

datos es lo que el agente ya averiguó, suelto: pares de nombre y valor, cortos, con lo que la persona dijo. Sirve para no volver a preguntarle lo que ya contestó. El resumen es prosa para leer; esto es para tu programa.

Todos los campos son opcionales y pueden no venir nunca: el agente manda lo que le dijeron, no lo que a vos te conviene. No los des por seguros y no te apoyes en que exista uno. Un valor que no reconozcas —una localidad mal escrita, un modelo que no vendés— se descarta y se pregunta: lo que no puede pasar es que un dato dudoso arruine lo que sigue.

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-chayana-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. Por un tiempo, la misma firma viaja también en x-agentia-firma, que es el nombre que usábamos antes de llamarnos Chayana: si tu complemento todavía lee esa, pasalo a x-chayana-firma, porque la vieja va a desaparecer.

const firma = req.headers["x-chayana-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 arrancar: sale por el canal en lugar del mensaje del agente, así la persona lee directo tu primera pregunta y no dos mensajes que dicen lo mismo. Si tu contrato dice que abrís vos, el agente no habla en ese turno: tenés que arrancar vos. Es mejor que un /enviar inmediato, que puede cruzarse con el mensaje del agente.

Si tu primera pregunta necesita más de un mensaje —fotos y después la pregunta con botones—, contestá con mensajes en lugar de responder:

{
  "mensajes": [
    { "mensaje": "Rectangular: la que mejor aprovecha patios angostos",
      "imagen": { "url": "https://tu-dominio/img/rectangular.png" } },
    { "mensaje": "Con solarium: escalón amplio para tomar sol",
      "imagen": { "url": "https://tu-dominio/img/solarium.png" } },
    { "mensaje": "¿Qué tipo de pileta estás buscando?",
      "opciones": { "tipo": "botones", "items": [
        { "id": "rect", "titulo": "Rectangular" },
        { "id": "sol", "titulo": "Con solarium" } ] } }
  ]
}

Salen en orden: cada uno recién cuando el canal aceptó el anterior, así la persona ve las fotos antes de la pregunta. Cada elemento tiene la forma del cuerpo de /enviar sin conversacion_id. Cada uno cuenta para el tope por hora. Las reglas exactas son cuatro:

• Van hasta cinco. Si mandás más, salen los cuatro primeros y el último: el último suele ser la pregunta, y la persona nunca se tiene que quedar sin ella.
• Cada elemento lleva mensaje y, como mucho, uno de opciones, imagen o documento. Si trae más de uno, sale el texto solo.
• Un elemento sin mensaje se descarta. Una imagen sin texto no sale.
• Si mandás responder y mensajes en la misma respuesta, gana mensajes y responder se ignora entero.

Ojo con esto: en la respuesta a un aviso no tenemos cómo avisarte un error —vos ya cerraste el POST y nadie va a leer lo que contestemos—, así que lo que no cumple se degrada en silencio. Nada corta la tanda: una imagen o un documento que no baja, o que el canal no muestra, sale como su texto solo; unas opciones que no cumplen salen numeradas; un elemento que el canal no acepta se saltea y siguen los demás. Por /enviar es al revés: ahí lo que no cumple lo rechazamos diciéndote el campo y el motivo. Si algo no te sale como esperabas en una respuesta a un aviso, probá el mismo cuerpo por /enviar y vas a leer qué está mal.

Los 8 segundos corren para contestar el aviso, no para que salgan los mensajes.

{
  "evento": "lead",
  "conversacion_id": "8f3c...",
  "sesion_id": "web-3f2a...",
  "canal": "whatsapp",
  "contacto": { "id": "5493515550144", "nombre": "Martín" },
  "lead": {
    "nombre": "Martín Ríos",
    "telefono": "351 555-0144",
    "email": null,
    "interes": "Pileta de 6 metros en Villa Allende",
    "notas": "Preguntó por la fecha de instalación.",
    "calor": "caliente"
  },
  "emitida": "2026-09-18T19:02:11.004Z"
}

sesion_id es tu id de sesión para esa persona, tal cual lo mandaste en /conversar o en /reportar: con eso unís el interesado con lo que ya tenés de ella cuando la charla empezó de tu lado, donde nuestro conversacion_id no te dice nada. Si consultaste con más de uno, va el último. Viene nulo si la persona solo habló con el agente.

calor es frio, tibio o caliente, según los criterios que el cliente le dio a su agente, y nulo si no definió ninguno. Qué hacer con él —una etiqueta, un orden, un aviso— lo decidís vos.

Contestá 2xx apenas lo guardes; el cuerpo se ignora. Si contestás un error o tardás más de ocho segundos, el agente se entera de que no quedó registrado y sigue atendiendo. No hay segundo intento.

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

También podés contestar con varios mensajes en orden, con mensajes en lugar de responder, igual que al recibir una conversación: salen uno detrás del otro, fotos antes que la pregunta, con las mismas reglas.

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 $ 20.400.000, 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.

El agente no espera a que la persona escriba: apenas soltás, retoma él con un mensaje desde donde quedó, usando tu contexto. Por eso conviene mandarlo siempre, y no despedirte vos antes de soltar: el cierre lo hace el agente.

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.