Chatbot de WhatsApp com IA: RAG, handoff para humano e custo

O ciclo tem cinco etapas: a mensagem chega ao seu webhook; o sistema filtra o que não deve responder (mensagens suas, grupos, spam); recupera o contexto (histórico da conversa e trechos da base de conhecimento); chama o modelo de IA com um prompt de sistema e esse contexto; e envia a resposta por send/text. Tudo isso precisa acontecer em segundos, e o webhook deve responder 2xx antes de a IA terminar.

O que separa um chatbot útil de um que atrapalha é o que ele não faz: não inventa preço, prazo ou política; não insiste quando o cliente pede uma pessoa; não responde fora do assunto. Isso se resolve com três decisões de projeto, tratadas abaixo: de onde vem o conhecimento (RAG), quando a conversa vai para um humano (handoff) e quanto cada resposta custa.

A API tem endpoints para o primeiro caminho: POST /agent/edit cria ou edita um agente (nome, provedor, modelo, prompt-base, limites), POST /knowledge/edit cadastra a base de conhecimento (tipos de arquivo pdf, txt, html e csv; exige a chave do provedor de IA configurada na instância) e POST /trigger/edit liga o agente a um gatilho (palavras que iniciam, ignorar grupos, atraso de resposta). A página do chatbot de WhatsApp com IA mostra o recurso no painel.

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 (geração aumentada por recuperação) é o padrão de buscar trechos relevantes no seu material e entregá-los ao modelo junto com a pergunta, em vez de esperar que o modelo saiba a resposta. É o que impede o bot de inventar o horário de funcionamento ou a política de troca: a resposta sai do texto que você forneceu.

O pipeline: reúna o material (FAQ, tabela de serviços, políticas, scripts de venda); quebre em trechos de tamanho moderado, cada um com um assunto; gere embeddings de cada trecho e guarde em um banco vetorial (ou no próprio Postgres com extensão vetorial); na hora da pergunta, busque os trechos mais próximos e coloque no prompt com a instrução de responder apenas com base neles. Se nada relevante for encontrado, o bot deve dizer que vai chamar uma pessoa, não improvisar.

Dois cuidados que fazem diferença: mantenha o material atualizado (preço velho no banco vetorial vira resposta errada com cara de certa) e guarde a origem de cada trecho, para auditar de onde saiu uma resposta.

O exemplo abaixo é um esqueleto em Node.js. As funções buscarTrechos e chamarModelo são pontos de troca: ligue-as ao seu banco vetorial e ao provedor de IA que você usar. O que importa aqui é a ordem: responder 2xx, filtrar, checar se há humano na conversa, recuperar contexto, gerar a resposta e enviar.

A estrutura do evento deve ser conferida em um log real; o código usa leitura defensiva. Para o desenho do webhook, veja o guia de webhook em produção.

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 é a passagem da conversa do bot para um humano. Defina regras explícitas, em código ou no prompt, e teste cada uma. Os gatilhos mais úteis: o cliente pede uma pessoa; o bot não encontrou trecho relevante; o assunto é sensível (reclamação, cobrança disputada, saúde, jurídico); o cliente repete a mesma pergunta duas vezes; a conversa passou de um número de trocas sem resolver; o sentimento é negativo.

Duas regras de convivência evitam constrangimento. Primeira: quando o humano assume, o bot se cala naquela conversa por um período (o exemplo usa quatro horas, valor seu) e volta só se alguém liberar. Segunda: avise o cliente na transição, com uma frase simples, e entregue ao atendente o resumo do que já foi dito, para ninguém pedir de novo a mesma informação.

O custo tem quatro partes: a conexão com o WhatsApp, o provedor de IA, a infraestrutura de busca e o tempo de manutenção. No ZapZap, a conexão custa R$15 por número ativo por mês, pré-pago, sem cobrança por mensagem (valores vigentes em preços). O provedor de IA cobra por volume de texto processado; o preço muda e varia por modelo, então consulte a tabela atual do provedor que você escolher em vez de usar um número de terceiros.

Para estimar sem chutar, meça. Rode uma semana com tráfego real em volume pequeno, registre quantos caracteres entram e saem por conversa e multiplique pelo preço da tabela do provedor. Os fatores que mais pesam: tamanho do prompt de sistema (repetido a cada resposta), quantidade de trechos de RAG injetados, tamanho do histórico enviado e comprimento das respostas. Reduzir qualquer um deles baixa o custo sem mexer no restante.

Alucinação: mesmo com RAG, o modelo pode errar. Mitigue com instrução de responder só com base no material, com temperatura baixa e revisando amostras de conversa toda semana. Dados pessoais: mensagens de clientes são dados pessoais; defina retenção, informe o uso de IA no atendimento e evite enviar dados sensíveis ao provedor sem base legal. A LGPD vale para o bot como para uma pessoa.

Risco do canal: respostas a quem escreveu primeiro são o uso mais seguro de um bot, mas nenhuma API não oficial elimina a possibilidade de restrição do número. Evite iniciar conversa fria com IA em volume. Veja o guia de anti-bloqueio e, para um passo a passo sem código, o artigo sobre resposta automática com IA.

• Webhook responde 2xx rápido e deduplica por id da mensagem
• Mensagens enviadas por você (fromMe) e grupos são ignoradas
• Há regra de handoff testada e o bot se cala quando o humano assume
• Sem trecho relevante, o bot diz que vai chamar uma pessoa
• O prompt manda responder só com base no material
• Material de RAG atualizado e com origem registrada
• Limite de tamanho de resposta e de histórico definido
• Amostra semanal de conversas revisada por uma pessoa
• Aviso ao cliente de que parte do atendimento é automatizado

Comece pequeno: um número, um tema (por exemplo, dúvidas de agendamento) e revisão diária na primeira semana. Aumente o escopo só quando as respostas estiverem estáveis. Para o primeiro envio e o webhook, o início rápido leva poucos minutos.