Chatbot de WhatsApp com IA: como montar sobre uma API

A arquitetura em uma frase

Uma API de WhatsApp não pensa, ela transporta. Ela recebe a mensagem do cliente, avisa o seu sistema e entrega a resposta que você mandar. A inteligência mora no seu backend, que conversa com o provedor de modelo que você escolher. Separar as duas coisas é o que permite trocar de modelo amanhã sem mexer na integração com o WhatsApp.

1. O cliente manda mensagem. A API dispara messages.received para o seu webhook.
2. O endpoint grava o evento numa fila e responde 200 na hora.
3. Um worker carrega o histórico daquele número e os dados de negócio relevantes.
4. O worker chama o modelo com instruções, contexto e a mensagem nova.
5. A resposta volta ao cliente com messages.sendText, ou o caso é passado para um atendente.

O passo 2 não é detalhe. Um modelo pode levar vários segundos para responder, e o webhook tem timeout de 30 segundos. Chamar a IA dentro da requisição do webhook gera reenvio e resposta duplicada.

Pseudocódigo do worker em Node

import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })

export async function handleMessage({ sessionId, data }) {
  if (data.fromMe || data.is_group) return
  if (await alreadyProcessed(data.id)) return

  const phone = data.from.jid.split('@')[0]
  const conversation = await loadConversation(sessionId, phone)

  if (conversation.assignedToHuman) {
    return forwardToAgentInbox(conversation, data)
  }

  conversation.append({ role: 'user', content: data.message })

  // seu provedor de LLM; a D-API não participa desta etapa
  const reply = await llm.generate({
    system: BUSINESS_RULES,
    context: await fetchCustomerFacts(phone),
    messages: conversation.lastTurns(12),
  })

  if (reply.needsHuman) {
    await conversation.assignToHuman(reply.reason)
    return dapi.messages.sendText({ sessionId, to: phone, text: 'Vou te passar para alguém do time. Um instante.' })
  }

  conversation.append({ role: 'assistant', content: reply.text })
  await dapi.messages.sendText({ sessionId, to: phone, text: reply.text })
}

Funções como loadConversation e llm.generate são suas. O que vem da D-API é o evento de entrada e o envio de saída. Para mais sobre o cliente, veja o SDK de Node.js.

Contexto e histórico: o que mandar ao modelo

O modelo não lembra de nada entre chamadas. Tudo que ele sabe sobre a conversa é o que você envia. Três camadas costumam bastar:

• Regras fixas: quem é o assistente, o que pode e o que não pode responder, tom de voz, quando chamar um humano.
• Fatos do cliente: pedidos em aberto, plano contratado, próxima consulta. Buscados no seu banco a cada mensagem, não confiados à memória do modelo.
• Últimas trocas: uma janela das mensagens recentes. Conversas longas ficam caras e lentas; resuma o que ficou para trás em vez de mandar tudo.

Guarde o histórico indexado por conexão e número. Num produto com vários clientes, cada um com o próprio WhatsApp, o sessionId identifica de qual cliente é a conversa, e misturar os dois é vazamento de dado.

Passagem para humano sem perder o cliente

Todo chatbot precisa de uma porta de saída. Os gatilhos mais comuns são pedido explícito ("quero falar com uma pessoa"), frustração repetida, assunto sensível como cancelamento ou reclamação, e baixa confiança do próprio modelo.

Quando o caso passa para humano, marque a conversa e pare de responder com IA até o atendente devolver. Mensagens que o atendente envia pelo celular do número chegam como messages.received com fromMe: true, o que ajuda a detectar que alguém assumiu. Se o seu produto já é uma plataforma de atendimento, esse é o mesmo fluxo descrito em API de WhatsApp para helpdesk.

Latência e custo: onde o tempo vai

No custo, a conta que importa é por conversa, não por mensagem. O modelo cobra pelo volume de texto processado. Do lado do WhatsApp, a D-API cobra por conexão, não por mensagem, então um bot que conversa muito não aumenta a fatura do canal. Os detalhes estão em preços.

Cuidados antes de colocar em produção

• Alucinação: preço, prazo, saldo e status sempre vêm do sistema, nunca do texto gerado.
• Injeção de instrução: o cliente pode escrever "ignore suas regras". Trate a mensagem como dado e limite as ações que a IA consegue disparar.
• LGPD: avise que há automação, minimize o que vai ao modelo, defina retenção do histórico e saiba onde o provedor processa os dados.
• Volume de saída: um bot que responde a tudo, inclusive a outro bot, pode entrar em loop. Limite respostas por conversa e ignore grupos se o caso de uso não for grupo.

Se a ideia é montar o fluxo com ferramentas visuais em vez de código, compare com o Typebot ou com os fluxos de automação.