WhatsApp AI chatbot: RAG, human handoff and cost

The cycle has five steps: the message reaches your webhook; the system filters what it should not answer (your own messages, groups, spam); it retrieves context (conversation history and knowledge base passages); it calls the AI model with a system prompt and that context; and it sends the reply through send/text. All of this has to happen in seconds, and the webhook must answer 2xx before the AI finishes.

What separates a useful chatbot from one that gets in the way is what it does not do: it does not invent prices, deadlines or policies; it does not insist when the customer asks for a person; it does not answer off-topic. That comes down to three design decisions, covered below: where knowledge comes from (RAG), when the conversation goes to a human (handoff) and how much each reply costs.

The API has endpoints for the first path: POST /agent/edit creates or edits an agent (name, provider, model, base prompt, limits), POST /knowledge/edit registers the knowledge base (file types pdf, txt, html and csv; it requires the AI provider key configured on the instance) and POST /trigger/edit connects the agent to a trigger (start words, ignore groups, reply delay). The WhatsApp AI chatbot page shows the feature in the dashboard.

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 (retrieval-augmented generation) is the pattern of searching your material for relevant passages and handing them to the model along with the question, instead of hoping the model knows the answer. It is what stops the bot from inventing opening hours or the return policy: the answer comes from the text you provided.

The pipeline: gather the material (FAQ, service table, policies, sales scripts); split it into moderate-sized chunks, each about one topic; generate embeddings for each chunk and store them in a vector database (or in Postgres itself with a vector extension); at question time, retrieve the closest chunks and put them in the prompt with the instruction to answer only from them. If nothing relevant is found, the bot should say it will bring in a person, not improvise.

Two cautions that make a difference: keep the material up to date (an old price in the vector store becomes a wrong answer that sounds right) and keep each chunk's source, so you can audit where an answer came from.

The example below is a Node.js skeleton. The buscarTrechos and chamarModelo functions are swap points: connect them to your vector database and the AI provider you use. What matters here is the order: answer 2xx, filter, check whether a human is in the conversation, retrieve context, generate the reply and send.

Check the event structure in a real log; the code reads defensively. For the webhook design, see the guide on webhooks in production.

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

Handoff is passing the conversation from the bot to a human. Define explicit rules, in code or in the prompt, and test each one. The most useful triggers: the customer asks for a person; the bot found no relevant passage; the topic is sensitive (complaint, disputed charge, health, legal); the customer repeats the same question twice; the conversation went past a number of turns without resolving; sentiment is negative.

Two coexistence rules avoid awkwardness. First: when the human takes over, the bot goes quiet in that conversation for a period (the example uses four hours, your value) and comes back only if someone releases it. Second: tell the customer about the transition with a simple sentence, and give the agent a summary of what has been said, so nobody asks for the same information again.

Cost has four parts: the WhatsApp connection, the AI provider, the search infrastructure and maintenance time. On ZapZap, the connection costs R$15 per active number per month, prepaid, with no per-message charge (current values on pricing). The AI provider charges by the volume of text processed; the price changes and varies by model, so check the current table of the provider you choose instead of using a third party's number.

To estimate without guessing, measure. Run a week of real traffic at small volume, log how many characters go in and out per conversation and multiply by the price in the provider's table. The factors that weigh most: system prompt size (repeated in every reply), the number of RAG passages injected, the size of the history sent and reply length. Reducing any of them lowers cost without touching the rest.

Hallucination: even with RAG, the model can be wrong. Mitigate with an instruction to answer only from the material, low temperature and a weekly review of sample conversations. Personal data: customer messages are personal data; set retention, tell people AI is used in service and avoid sending sensitive data to the provider without a legal basis. Data protection law applies to the bot as to a person.

Channel risk: replying to people who wrote first is the safest use of a bot, but no unofficial API removes the possibility of number restriction. Avoid starting cold conversations with AI at volume. See the anti-ban guide and, for a no-code walkthrough, the article on automatic replies with AI.

• Webhook answers 2xx fast and deduplicates by message id
• Messages sent by you (fromMe) and groups are ignored
• There is a tested handoff rule and the bot goes quiet when the human takes over
• With no relevant passage, the bot says it will bring in a person
• The prompt says to answer only from the material
• RAG material is up to date and its source is recorded
• Reply length and history limits are defined
• A weekly sample of conversations is reviewed by a person
• Customers are told part of the service is automated

Start small: one number, one topic (for example, appointment questions) and daily review in the first week. Expand the scope only when replies are stable. For the first send and the webhook, the quick start takes a few minutes.