Chatbot com IA no WhatsApp pela API oficial: arquitetura e código

Atualizado em 25/10/2026

Para conectar um chatbot ou agente de IA ao WhatsApp pela API oficial, você recebe cada mensagem por webhook, responde 200 na hora, coloca o evento numa fila e deixa um worker montar o contexto, chamar o modelo de linguagem e enviar a resposta pela API. A resposta livre do bot só pode sair dentro da janela de 24 horas aberta pelo cliente, e a política da Meta exige um caminho claro para atendimento humano. Os termos da Meta também proíbem usar a plataforma para oferecer assistentes de IA de uso geral como produto principal, com exceções em alguns países, entre eles o Brasil.

Este guia mostra a arquitetura, as regras que afetam o bot e um exemplo funcional em Node.js usando a Vectalk, que repassa os mesmos payloads e webhooks da Meta.

Arquitetura: webhook, fila, LLM e resposta

Cliente no WhatsApp
      │
      ▼
Meta ──POST──▶ Vectalk ──POST──▶ /webhook (responde 200 e enfileira)
                                     │
                                     ▼
                                   Fila
                                     │
                                     ▼
                Worker: deduplica ▶ carrega histórico ▶ decide (bot ou humano)
                                     │
                         ┌───────────┴───────────┐
                         ▼                       ▼
                   LLM gera resposta      Atendente humano
                         │
                         ▼
             POST /api/messages (Vectalk) ──▶ Meta ──▶ Cliente

Cada peça tem uma função clara:

Componente	Responsabilidade	Cuidado principal
Webhook	Receber o evento, validar e responder 200	Não chamar o LLM dentro da requisição
Fila	Desacoplar recebimento e processamento	Garantir nova tentativa se o worker cair
Deduplicação	Ignorar eventos repetidos pelo ID `wamid`	Guardar IDs processados por alguns dias
Histórico	Montar o contexto da conversa por `wa_id`	Limitar o tamanho para controlar custo e latência
Roteador	Decidir se o bot responde ou se a conversa está com humano	Respeitar o estado de handoff
LLM	Gerar a resposta dentro do escopo do negócio	Prompt com limites claros e tempo máximo de resposta
Envio	Chamar a API e guardar o ID da mensagem enviada	Tratar erros e checar a janela de 24 horas

Por que a fila é obrigatória

Um modelo de linguagem pode levar vários segundos para responder. A Vectalk espera HTTP 200 em menos de 20 segundos e reenvia o evento se não receber, segundo a documentação de webhooks. Se o endpoint esperar o LLM, um pico de mensagens gera reenvios, respostas duplicadas e custo em dobro. Com a fila, o webhook só grava o evento e responde.

O artigo webhooks da API do WhatsApp cobre o formato dos eventos, a deduplicação e o tratamento de status.

Marcar como lida e mostrar “digitando”

A Cloud API permite marcar a mensagem recebida como lida e exibir o indicador de digitação na mesma chamada. Segundo a documentação de indicadores de digitação, o indicador some quando você responde ou depois de 25 segundos, o que vier primeiro. A Meta recomenda exibi-lo só quando você realmente vai responder.

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgLNTUx...",
  "typing_indicator": { "type": "text" }
}

Na Vectalk, essa chamada vai para POST /api/messages, o mesmo endpoint documentado para marcar como lida.

A janela de 24 horas define o que o bot pode enviar

Quando o cliente manda uma mensagem, abre-se uma janela de atendimento de 24 horas, renovada a cada nova mensagem dele. Dentro dela, o bot pode responder com texto livre, mídia e mensagens interativas. Fora dela, só templates aprovados, conforme a documentação de mensagens de serviço e janela de atendimento.

Na prática, isso muda o desenho do agente:

O bot é reativo. Ele responde ao que o cliente perguntou. Para retomar contato depois de 24 horas, o sistema precisa de um template, e não de texto gerado pelo LLM.
Respostas demoradas podem perder a janela. Se o bot depende de um processo lento (análise de documento, consulta a outro sistema), registre o horário da última mensagem do cliente e cheque antes de enviar.
Botões e listas ajudam o LLM. Em vez de pedir que o cliente digite “1” ou “2”, o bot pode enviar opções clicáveis. Veja mensagens interativas na API do WhatsApp.

O artigo janela de 24 horas do WhatsApp detalha as regras de abertura e renovação.

Quanto custa cada resposta do bot

As respostas livres dentro da janela são mensagens de serviço. Desde 1º de outubro de 2026, cada número comercial tem 1.000 mensagens de serviço gratuitas por mês, e a Meta cobra a partir da 1.001ª, segundo a página de preços. Para destinatários no Brasil, a tarifa de serviço é de R$ 0,0350 por mensagem entregue. Um bot que responde em três mensagens curtas custa três vezes mais do que um que responde em uma só, então vale juntar a resposta.

A esse valor soma-se o custo do próprio modelo de linguagem, que depende do provedor e do tamanho do contexto.

Handoff para humano

A Política de Mensagens do WhatsApp Business permite automação dentro da janela de 24 horas, mas exige caminhos de escalonamento rápidos, claros e diretos. As opções listadas incluem transferência para um atendente humano na conversa, número de telefone, e-mail, suporte no site, visita a uma loja ou formulário de suporte.

Um bot de atendimento precisa, no mínimo, de três gatilhos de handoff:

Pedido explícito. O cliente escreve “atendente”, “falar com uma pessoa” ou clica num botão de ajuda humana.
Baixa confiança. O LLM indica que não sabe responder ou o assunto está fora do escopo definido.
Assunto sensível. Reclamação, cancelamento, cobrança contestada ou qualquer tema que a empresa decida tratar só com pessoas.

Estado da conversa	Quem responde	Como sai do estado
`bot`	Agente de IA	Gatilho de handoff
`aguardando_humano`	Ninguém responde automaticamente; o bot avisa o tempo de espera uma única vez	Atendente assume
`humano`	Atendente, pela ferramenta de atendimento	Atendente encerra ou a conversa fica inativa

Se o número usa coexistência, o atendente pode responder pelo app WhatsApp Business no celular. As mensagens enviadas pelo app chegam ao seu sistema como eventos de eco, e o roteador pode usá-las para colocar a conversa em humano automaticamente, sem que o bot responda por cima.

O que a Meta permite para chatbots de IA

Os Termos da Meta para a Plataforma do WhatsApp Business, na cláusula 4.7, tratam de “Provedores de IA”: fornecedores e desenvolvedores de tecnologias de inteligência artificial ou aprendizado de máquina, como grandes modelos de linguagem, plataformas de IA generativa e assistentes de IA de uso geral, conforme a Meta determinar. Eles são proibidos de usar a plataforma para oferecer essas tecnologias quando elas são a funcionalidade principal, e não incidental ou auxiliar.

O que isso significa para quem constrói bots:

Bot de atendimento da própria empresa. Um agente que tira dúvidas sobre pedidos, agenda horários ou explica produtos da empresa usa a IA como ferramenta do atendimento. A Meta decide os casos, mas esse é o uso que os termos não miram.
Assistente de uso geral como produto. Oferecer um “ChatGPT no WhatsApp” para o público, em que a conversa com a IA é o próprio serviço, é o caso proibido, salvo nos países em que a Meta é legalmente obrigada a permitir.
Brasil. A página de preços para Provedores de IA lista o Brasil (+55) entre os mercados onde Provedores de IA podem enviar mensagens de serviço desde 11 de março de 2026, com tarifa própria. Nesses envios, o webhook de status traz a categoria general_purpose_ai. Essa regra vale só para Provedores de IA; o preço das demais empresas não muda.
Dados para treino. Os termos proíbem usar dados da plataforma para criar, treinar ou melhorar modelos de IA. Eles permitem usar esses dados para ajustar um modelo de uso exclusivo da empresa, desde que não sirvam para outros modelos. Revise os termos do seu provedor de LLM sobre retenção e treino.

Os termos foram atualizados em 23 de setembro de 2026. Releia a cláusula antes de lançar um produto em que a IA seja o centro da oferta.

Exemplo em Node.js

O exemplo abaixo usa Express, uma fila em memória e a API da Vectalk. Em produção, troque a fila por um serviço persistente (Redis, SQS, RabbitMQ) e o Map por um banco. A função gerarResposta é o ponto onde entra o SDK do seu provedor de LLM.

import express from 'express';

const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const TOKEN = process.env.VECTALK_TOKEN; // token de instância
const JANELA_MS = 24 * 60 * 60 * 1000;
const GATILHOS_HUMANO = /\b(atendente|humano|pessoa|reclama|cancelar)\b/i;

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

const fila = [];
const processados = new Set();      // IDs wamid já tratados
const conversas = new Map();        // wa_id -> { estado, historico, ultimaEntrada }

// 1. Webhook: só valida, enfileira e responde 200
app.post('/webhook', (req, res) => {
  for (const entry of req.body.entry ?? []) {
    for (const change of entry.changes ?? []) {
      for (const msg of change.value?.messages ?? []) fila.push(msg);
    }
  }
  res.sendStatus(200);
});

// 2. Envio pela Vectalk (mesmo payload da Meta)
async function enviar(payload) {
  const r = await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ messaging_product: 'whatsapp', ...payload }),
  });
  if (!r.ok) throw new Error(`Falha no envio: ${r.status} ${await r.text()}`);
  return r.json();
}

// 3. Ponto de integração com o LLM
async function gerarResposta(historico) {
  // Chame aqui o SDK do seu provedor, com um prompt de sistema que limite
  // o escopo ao seu negócio e peça para responder "HANDOFF" quando não souber.
  throw new Error('Implemente a chamada ao LLM');
}

// 4. Worker
async function processar(msg) {
  if (processados.has(msg.id)) return;
  processados.add(msg.id);

  const c = conversas.get(msg.from) ?? { estado: 'bot', historico: [], ultimaEntrada: 0 };
  c.ultimaEntrada = Number(msg.timestamp) * 1000;
  conversas.set(msg.from, c);

  if (c.estado !== 'bot') return; // conversa com humano: o bot fica em silêncio

  if (msg.type !== 'text') {
    await enviar({ to: msg.from, type: 'text', text: { body: 'Por enquanto entendo só texto. Pode escrever sua dúvida?' } });
    return;
  }

  const texto = msg.text.body;
  c.historico.push({ role: 'user', content: texto });
  c.historico = c.historico.slice(-20); // limita o contexto

  if (GATILHOS_HUMANO.test(texto)) return transferir(msg.from, c);

  await enviar({ status: 'read', message_id: msg.id, typing_indicator: { type: 'text' } });

  const resposta = await gerarResposta(c.historico);
  if (resposta.trim() === 'HANDOFF') return transferir(msg.from, c);

  if (Date.now() - c.ultimaEntrada > JANELA_MS) return; // janela fechou: precisa de template

  await enviar({ to: msg.from, type: 'text', text: { body: resposta } });
  c.historico.push({ role: 'assistant', content: resposta });
}

async function transferir(waId, c) {
  c.estado = 'aguardando_humano';
  await enviar({ to: waId, type: 'text', text: { body: 'Vou chamar uma pessoa do time. Em instantes alguém continua por aqui.' } });
  // Notifique a ferramenta de atendimento (fila de tickets, Slack, CRM).
}

setInterval(async () => {
  const msg = fila.shift();
  if (!msg) return;
  try { await processar(msg); } catch (e) { console.error(e); }
}, 50);

app.listen(3000);

O que o exemplo já resolve e o que falta para produção:

Resolve: resposta imediata ao webhook, deduplicação por wamid, estado de handoff, limite de contexto, checagem da janela e indicador de digitação.
Falta: fila persistente com novas tentativas, banco para histórico e estado, tempo máximo na chamada ao LLM, registro de custos a partir do webhook de status e um painel para o atendente assumir e devolver a conversa ao bot.

Boas práticas para o agente

Escopo fechado. O prompt de sistema deve dizer o que o bot faz e o que não faz. Preços, prazos e políticas devem vir de dados do seu sistema, e não da memória do modelo.
Respostas curtas. No WhatsApp, uma mensagem de três linhas funciona melhor do que um texto longo. Isso também reduz o número de mensagens cobradas.
Identifique o bot. Deixe claro que o cliente está falando com um assistente virtual e como chegar a uma pessoa.
Registre tudo. Guarde a pergunta, a resposta, o modelo usado e o tempo de resposta. Sem isso, não dá para auditar uma resposta errada.
Teste com mensagens reais. Áudio, foto de comprovante e figurinha chegam todo dia. Decida o que o bot faz com cada tipo antes de ir para produção.

Perguntas frequentes

Posso usar qualquer LLM com a API oficial?

A API do WhatsApp não restringe o modelo que você usa no seu servidor. O que os termos da Meta regulam é o uso: a IA como apoio ao atendimento da empresa é diferente de oferecer um assistente de uso geral como produto principal.

O bot pode mandar a primeira mensagem para o cliente?

Não com texto livre. Para iniciar contato ou retomar depois de 24 horas, é preciso um template aprovado. Veja templates da API do WhatsApp.

Como evito que o bot responda duas vezes à mesma mensagem?

Guarde o ID wamid de cada mensagem processada e ignore repetições. Reenvios de webhook acontecem sempre que o endpoint demora ou falha.

O bot pode responder áudios?

O webhook entrega o ID da mídia, que você baixa pela API de mídia e transcreve com o serviço que preferir. A transcrição e o custo dela ficam por sua conta.

Preciso de algum cadastro especial na Meta para usar IA?

Para um bot de atendimento da própria empresa, a documentação consultada não descreve cadastro adicional. Se o seu produto é um assistente de IA de uso geral, leia a cláusula 4.7 dos termos e a página de Provedores de IA antes de começar.

Comece na Vectalk

Na Vectalk, seu bot recebe os mesmos webhooks da Meta e envia com os mesmos payloads, usando um token para todas as contas. A cobrança das mensagens vem na fatura da Vectalk, sem cartão cadastrado na Meta, e a coexistência permite que o time humano continue no app. Crie sua conta em apps.vectalk.com.br/register e consulte a documentação.

Fontes oficiais consultadas em 25/10/2026: Termos da Meta para a Plataforma do WhatsApp Business (atualizados em 23/09/2026), Política de Mensagens do WhatsApp Business, Preços para Provedores de IA, Preços na plataforma do WhatsApp Business, Mensagens de serviço e janela de atendimento, Indicadores de digitação, Webhooks na documentação da Vectalk.