Chatbot de WhatsApp con IA: RAG, traspaso a humano y costo

El ciclo tiene cinco etapas: el mensaje llega a tu webhook; el sistema filtra lo que no debe responder (mensajes tuyos, grupos, spam); recupera el contexto (historial de la conversación y fragmentos de la base de conocimiento); llama al modelo de IA con un prompt de sistema y ese contexto; y envía la respuesta por send/text. Todo eso debe ocurrir en segundos, y el webhook debe responder 2xx antes de que la IA termine.

Lo que separa un chatbot útil de uno que estorba es lo que no hace: no inventa precio, plazo ni política; no insiste cuando el cliente pide una persona; no responde fuera del tema. Eso se resuelve con tres decisiones de diseño, tratadas abajo: de dónde viene el conocimiento (RAG), cuándo la conversación pasa a un humano (handoff) y cuánto cuesta cada respuesta.

La API tiene endpoints para el primer camino: POST /agent/edit crea o edita un agente (nombre, proveedor, modelo, prompt base, límites), POST /knowledge/edit registra la base de conocimiento (tipos de archivo pdf, txt, html y csv; exige la clave del proveedor de IA configurada en la instancia) y POST /trigger/edit conecta el agente a un disparador (palabras que inician, ignorar grupos, retraso de respuesta). La página del chatbot de WhatsApp con IA muestra el recurso en el panel.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/agent/edit \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"agent":{"name":"Atendimento","provider":"SEU_PROVEDOR","model":"SEU_MODELO","apikey":"CHAVE_DO_PROVEDOR","basePrompt":"Você atende clientes da clínica X. Responda só com base no material. Se não souber, diga que vai chamar uma pessoa.","maxTokens":500,"temperature":50}}'

RAG (generación aumentada por recuperación) es el patrón de buscar fragmentos relevantes en tu material y entregárselos al modelo junto con la pregunta, en vez de esperar que el modelo sepa la respuesta. Es lo que impide que el bot invente el horario de atención o la política de cambios: la respuesta sale del texto que le diste.

El pipeline: reúne el material (FAQ, tabla de servicios, políticas, guiones de venta); córtalo en fragmentos de tamaño moderado, cada uno sobre un tema; genera embeddings de cada fragmento y guárdalos en una base vectorial (o en el propio Postgres con extensión vectorial); a la hora de la pregunta, busca los fragmentos más cercanos y ponlos en el prompt con la instrucción de responder solo con base en ellos. Si no se encuentra nada relevante, el bot debe decir que va a llamar a una persona, no improvisar.

Dos cuidados que marcan la diferencia: mantén el material actualizado (un precio viejo en la base vectorial se vuelve una respuesta errada que parece correcta) y guarda el origen de cada fragmento, para auditar de dónde salió una respuesta.

El ejemplo de abajo es un esqueleto en Node.js. Las funciones buscarTrechos y chamarModelo son puntos de cambio: conéctalas a tu base vectorial y al proveedor de IA que uses. Lo que importa aquí es el orden: responder 2xx, filtrar, revisar si hay un humano en la conversación, recuperar contexto, generar la respuesta y enviar.

La estructura del evento debe comprobarse en un log real; el código usa lectura defensiva. Para el diseño del webhook, mira la guía de webhook en producción.

import express from "express";

const app = express();
app.use(express.json());

const BASE = "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE_ID;
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

const comHumano = new Map(); // number -> expiry (ms)
const vistos = new Set();    // handled message ids

async function buscarTrechos(pergunta) { /* query your vector store */ return []; }
async function chamarModelo({ sistema, historico, pergunta, trechos }) { /* call your AI provider */ return "..."; }

async function enviar(number, text) {
  const r = await fetch(BASE + "/send/text", { method: "POST", headers, body: JSON.stringify({ number, text }) });
  if (!r.ok) throw new Error("send failed " + r.status + ": " + (await r.text()));
}

app.post("/webhook/whatsapp", (req, res) => {
  res.sendStatus(200);
  responder(req.body).catch((e) => console.error(e));
});

async function responder(evento) {
  const msg = evento?.message ?? evento?.data ?? evento;
  if (msg?.fromMe) return;
  const id = msg?.messageid ?? msg?.id;
  if (id && vistos.has(id)) return;
  if (id) vistos.add(id);

  const numero = msg?.sender ?? msg?.from;
  const texto = msg?.text ?? msg?.body ?? "";
  if (!numero || !texto) return;

  if ((comHumano.get(numero) ?? 0) > Date.now()) return;

  if (/atendente|humano|pessoa|reclama/i.test(texto)) {
    comHumano.set(numero, Date.now() + 4 * 60 * 60 * 1000);
    await enviar(numero, "Certo, vou chamar uma pessoa da equipe para continuar com você.");
    return;
  }

  const trechos = await buscarTrechos(texto);
  if (trechos.length === 0) {
    comHumano.set(numero, Date.now() + 4 * 60 * 60 * 1000);
    await enviar(numero, "Essa eu prefiro confirmar com a equipe. Já te respondo por aqui.");
    return;
  }
  const resposta = await chamarModelo({
    sistema: "Responda apenas com base nos trechos. Se faltar informação, diga que vai chamar uma pessoa.",
    historico: [],
    pergunta: texto,
    trechos,
  });
  await enviar(numero, resposta);
}

app.listen(3000);

El handoff es el traspaso de la conversación del bot a un humano. Define reglas explícitas, en código o en el prompt, y prueba cada una. Los disparadores más útiles: el cliente pide una persona; el bot no encontró un fragmento relevante; el tema es sensible (reclamo, cobro en disputa, salud, jurídico); el cliente repite la misma pregunta dos veces; la conversación superó un número de intercambios sin resolverse; el sentimiento es negativo.

Dos reglas de convivencia evitan situaciones incómodas. Primera: cuando el humano asume, el bot se calla en esa conversación por un período (el ejemplo usa cuatro horas, valor tuyo) y vuelve solo si alguien lo libera. Segunda: avisa al cliente en la transición, con una frase simple, y entrégale al agente el resumen de lo que ya se dijo, para que nadie pida otra vez la misma información.

El costo tiene cuatro partes: la conexión con WhatsApp, el proveedor de IA, la infraestructura de búsqueda y el tiempo de mantenimiento. En ZapZap, la conexión cuesta R$15 por número activo al mes, prepago, sin cobro por mensaje (valores vigentes en precios). El proveedor de IA cobra por volumen de texto procesado; el precio cambia y varía según el modelo, así que consulta la tabla actual del proveedor que elijas en vez de usar un número de terceros.

Para estimar sin adivinar, mide. Corre una semana con tráfico real en volumen pequeño, registra cuántos caracteres entran y salen por conversación y multiplica por el precio de la tabla del proveedor. Los factores que más pesan: tamaño del prompt de sistema (se repite en cada respuesta), cantidad de fragmentos de RAG inyectados, tamaño del historial enviado y largo de las respuestas. Reducir cualquiera de ellos baja el costo sin tocar el resto.

Alucinación: aun con RAG, el modelo puede equivocarse. Mitígalo con la instrucción de responder solo con base en el material, con temperatura baja y revisando muestras de conversaciones cada semana. Datos personales: los mensajes de clientes son datos personales; define retención, informa el uso de IA en la atención y evita enviar datos sensibles al proveedor sin base legal. La protección de datos vale para el bot igual que para una persona.

Riesgo del canal: responder a quien escribió primero es el uso más seguro de un bot, pero ninguna API no oficial elimina la posibilidad de restricción del número. Evita iniciar conversaciones en frío con IA en volumen. Mira la guía de antibloqueo y, para un paso a paso sin código, el artículo sobre respuesta automática con IA.

• El webhook responde 2xx rápido y deduplica por id del mensaje
• Los mensajes enviados por ti (fromMe) y los grupos se ignoran
• Hay una regla de handoff probada y el bot se calla cuando el humano asume
• Sin fragmento relevante, el bot dice que va a llamar a una persona
• El prompt manda responder solo con base en el material
• El material de RAG está actualizado y con el origen registrado
• Está definido el límite de tamaño de respuesta y de historial
• Una persona revisa cada semana una muestra de conversaciones
• Se avisa al cliente que parte de la atención es automatizada

Empieza pequeño: un número, un tema (por ejemplo, dudas de agenda) y revisión diaria la primera semana. Amplía el alcance solo cuando las respuestas estén estables. Para el primer envío y el webhook, el inicio rápido lleva pocos minutos.