Criar um chatbot no WhatsApp deixou de ser um projeto restrito a grandes equipes de desenvolvimento. Com uma API de mensageria, uma plataforma de automação e um modelo de linguagem, é possível construir fluxos capazes de receber perguntas, interpretar o contexto e responder automaticamente.
Neste guia, você vai aprender como estruturar um chatbot de IA usando n8n, Z-API e o ChatGPT. O fluxo apresentado é baseado no tutorial em vídeo indicado para este conteúdo e foi complementado com informações da documentação técnica das ferramentas.
A arquitetura é simples: o Z-API conecta o número de WhatsApp ao sistema; o n8n recebe os eventos e organiza o fluxo; e a IA interpreta as mensagens e gera respostas.
A memória de conversa permite que o chatbot considere interações anteriores, enquanto webhooks e configurações de envio fazem a resposta retornar ao cliente.
O resultado não é apenas uma resposta automática com palavras-chave. É uma operação conversacional que pode ser integrada a CRM, e-commerce, agenda, ERP, base de conhecimento e sistemas internos.
O que é e como criar um chatbot no WhatsApp com IA?
Um chatbot no WhatsApp com IA é um sistema capaz de receber uma mensagem, interpretar seu conteúdo, gerar uma resposta e enviá-la ao usuário sem que um atendente execute manualmente cada etapa.
Bots tradicionais costumam depender de menus, palavras-chave e caminhos definidos. Já um chatbot conectado a um modelo de linguagem consegue interpretar perguntas em linguagem natural e produzir respostas mais flexíveis.
Isso não significa deixar a IA responder sem controle. Um chatbot profissional precisa de objetivo, contexto, limites, fontes confiáveis e regras de handoff para atendimento humano.
No fluxo deste tutorial:
- O cliente envia uma mensagem pelo WhatsApp.
- O Z-API encaminha o evento ao n8n por webhook.
- O n8n identifica o contato e extrai a mensagem.
- O modelo da OpenAI recebe o texto e as instruções.
- A memória, quando configurada, recupera o contexto da sessão.
- O n8n recebe a resposta gerada.
- O Z-API envia o texto ao WhatsApp.
O Z-API oferece API REST e webhooks para interagir com o WhatsApp e receber eventos do número conectado.
Quais ferramentas são necessárias?
Para reproduzir essa arquitetura, você precisa de uma instância Z-API, uma conta no n8n e uma credencial da OpenAI.
| Componente | Função | Informação necessária |
| Z-API | Receber e enviar mensagens | Instance ID, Token e, se ativado, Client Token |
| n8n | Orquestrar eventos e integrações | Workflow e URL HTTPS para webhook |
| OpenAI | Interpretar e gerar respostas | API Key e modelo |
| Memória | Manter contexto entre interações | Identificador de sessão e configuração de memória |
| CRM/sistema interno | Consultar ou registrar dados | API ou credenciais correspondentes |
O Z-API também possui um node comunitário para n8n, que pode simplificar operações de envio. Como alternativa, é possível usar o HTTP Request com o endpoint send-text da API.
No n8n Cloud, a disponibilidade de community nodes depende das regras de verificação da plataforma; em ambientes self-hosted, a instalação pode ser feita diretamente.
Como configurar o recebimento de mensagens pelo Z-API?
O primeiro passo é criar um fluxo no n8n que aceite requisições externas. Adicione o node Webhook, configure o método como POST e copie a URL gerada.
O n8n oferece uma URL de teste e outra de produção. Durante o desenvolvimento, use a URL de teste para visualizar os dados recebidos. Depois de publicar o workflow, utilize a URL de produção.
No Z-API, o webhook de recebimento é configurado com uma requisição PUT para update-webhook-received. O endereço informado precisa utilizar HTTPS.
Um exemplo é:
| curl –request PUT \ –url https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-received \ –header ‘Client-Token: SEU_CLIENT_TOKEN’ \ –header ‘Content-Type: application/json’ \ –data ‘{ “value”: “https://seu-n8n.com/webhook/whatsapp-receive” }’ |
Substitua os valores pelas credenciais e pela URL da sua própria instância. Nunca publique tokens em artigos, repositórios ou capturas de tela.
Ajuste os filtros antes de testar
Se o chatbot não precisa processar mensagens enviadas pelo próprio número, desative essa notificação. O Z-API possui o endpoint update-notify-sent-by-me para controlar esse comportamento.
Isso evita que o bot processe sua própria resposta e entre em um ciclo de mensagens.
Para ignorar grupos, o webhook informa o atributo isGroup. No n8n, você pode adicionar um filtro para permitir que o fluxo continue apenas quando isGroup for false.
Os filtros devem seguir o caso de uso: um chatbot de atendimento individual pode ignorar grupos, enquanto outras automações podem precisar processá-los.
Ainda não sabe todas as possibilidades do Z-API? Leia nosso conteúdo e veja como a API do Z-API pode ser usada na sua automação.
Como tratar o payload recebido no n8n?
Depois do Webhook, você pode adicionar um node Code em JavaScript para transformar o evento recebido em uma estrutura previsível.
O webhook do Z-API inclui campos como telefone, identificador da mensagem, timestamp, origem e tipo do conteúdo. Para mensagens de texto, o conteúdo aparece em text.message.
Um exemplo de normalização é:
| const body = $json.body ?? $json; return [{ json: { phone: body.phone, text: body.text?.message?.trim() ?? ”, messageId: body.messageId, timestamp: body.momment, fromMe: body.fromMe, isGroup: body.isGroup, raw: body }}]; |
Os campos phone, messageId, momment, fromMe e isGroup fazem parte do callback documentado pelo Z-API.
Esse exemplo considera mensagens de texto. Imagens, áudios, vídeos, documentos e outros conteúdos possuem estruturas próprias e devem ser tratados conforme o tipo recebido.
Depois da normalização, utilize nodes de filtro para interromper o fluxo quando não houver telefone ou texto, quando fromMe for true ou quando o evento não fizer parte do caso de uso.
Validar o payload antes de chamar a OpenAI evita processamento desnecessário, erros e loops de resposta.
Aprofunde-se no tema: Como usar webhooks do WhatsApp para criar automações em tempo real com o Z-API.
Como configurar o AI Agent no n8n?
Com os dados organizados, adicione o node AI Agent. Ele recebe a entrada, utiliza um modelo de chat e pode acionar ferramentas para executar tarefas.
Nas versões atuais do n8n, o AI Agent funciona como Tools Agent e precisa ter pelo menos uma ferramenta conectada.
Para um chatbot que apenas gera respostas, um Basic LLM Chain pode ser suficiente. Já para consultar pedidos, agendas ou sistemas internos, utilize o AI Agent com tools e permissões adequadas.
Conecte o modelo de chat da OpenAI
Adicione o OpenAI Chat Model, configure sua API Key e escolha um modelo disponível.
O vídeo pode utilizar um modelo específico, mas a escolha deve considerar custo, velocidade e complexidade do atendimento, já que os modelos disponíveis mudam ao longo do tempo. A OpenAI publica as opções atuais e seus preços na documentação da API.
Modelos mais econômicos podem atender bem FAQs e triagens, enquanto tarefas mais complexas podem exigir maior capacidade.
Como escrever o prompt de sistema?
O prompt define objetivo, comportamento, limites e critérios de encaminhamento do chatbot.
Por exemplo:
| Você é o assistente virtual da Flor & Casa, uma floricultura especializada em buquês e presentes.Ajude clientes a escolher produtos e informe prazos e horários apenas quando esses dados estiverem disponíveis.Responda em português brasileiro, com clareza e objetividade. Não invente preços, estoque ou prazos.Para pagamentos, alterações de pedidos, reclamações ou solicitações de atendimento humano, encaminhe a conversa para a equipe.Não afirme que uma ação foi executada sem confirmação do sistema. |
A mesma estrutura pode ser adaptada para diferentes negócios.
O prompt orienta o modelo, mas controles críticos devem estar no workflow e nas permissões das ferramentas, não apenas nas instruções.
Como adicionar memória à conversa?
Sem memória, cada mensagem pode ser processada sem o contexto das anteriores. Com memória, o agente consegue considerar interações recentes.
No tutorial, o Simple Memory pode utilizar o telefone como chave de sessão:
| Session Key: {{$json.phone}} Context Window Length: 10 |
O Context Window Length representa o número de interações anteriores consideradas no contexto.
O telefone é uma chave prática, mas deve ser normalizado. Em operações maiores, um ID interno do CRM pode ser mais adequado.
Memória não é base de conhecimento. Para preços, produtos, políticas ou dados atualizados, o agente deve consultar fontes específicas, como APIs, bancos de dados ou RAG.
Também há uma limitação importante: o n8n orienta não utilizar Simple Memory em workflows de produção executados em queue mode. Nesse cenário, prefira uma memória persistente, como Redis ou Postgres.
Aproveite e conheça também outras plataformas para automatizar fluxos de trabalho com webhooks.
Como devolver a resposta ao WhatsApp?
Depois que o AI Agent gerar a resposta, você pode utilizar um node Code para validar ou normalizar o texto antes do envio. Essa etapa é opcional.
O conteúdo do agente costuma aparecer em um campo como output, mas confirme a estrutura no resultado real do node antes de mapear a expressão.
No tutorial, a resposta pode ser enviada pelo node comunitário Z-API WhatsApp, utilizando a operação Send Text Message. O telefone vem do webhook e a mensagem da saída do agente.
Também é possível enviar diretamente pela API do Z-API:
| curl –request POST \ –url https://api.z-api.io/instances/{instanceId}/token/{token}/send-text \ –header ‘Client-Token: SEU_CLIENT_TOKEN’ \ –header ‘Content-Type: application/json’ \ –data ‘{ “phone”: “5511999999999”, “message”: “Olá! Como posso ajudar?” }’ |
O endpoint send-text utiliza phone e message no corpo da requisição. No n8n, os valores devem vir dos nodes anteriores:
| Phone: {{$node[“Code – Normalizar entrada”].json.phone}}Message: {{$node[“AI Agent”].json.output}} |
Evite deixar telefone ou mensagem fixos no workflow. Quando o envio é aceito, o Z-API retorna identificadores como zaapId, messageId e id, que podem ser armazenados para correlação, acompanhamento de status e diagnóstico.
Como testar o chatbot sem enviar mensagens repetidas?
Durante o desenvolvimento, você pode capturar o JSON de uma execução real e reutilizá-lo nos testes.
O n8n permite fixar dados de um node para reutilizá-los em execuções manuais, evitando novas chamadas ao sistema externo. (github.com)
Capture uma mensagem real, salve o payload e utilize-o para testar normalização, prompt e memória.
Se o node de envio estiver ativo, o workflow ainda poderá enviar uma mensagem real, portanto interrompa o fluxo antes dessa etapa enquanto estiver testando apenas a lógica.
Teste também saudações, perguntas incompletas, solicitações fora do escopo, pedido de atendimento humano e diferentes tipos de mídia.
Mensagens de texto, imagem, áudio, vídeo e documento possuem estruturas diferentes. Os arquivos recebidos pelo Z-API ficam disponíveis por 30 dias e exigem tratamento específico conforme o tipo. (developer.z-api.io)
Como evitar loops e respostas duplicadas?
Um loop pode acontecer quando o bot processa uma mensagem enviada pelo próprio número como se fosse uma nova entrada.
Quando esses eventos não forem necessários, desative notifySentByMe. O Z-API oferece uma configuração específica para isso. (developer.z-api.io)
Se precisar manter essa opção, filtre eventos com fromMe: true.
Também é recomendável armazenar o messageId dos eventos processados e ignorar identificadores já tratados. Essa idempotência reduz o risco de processamento duplicado.
Se o cliente enviar várias mensagens rapidamente, podem ocorrer execuções paralelas. Para fluxos mais complexos, utilize filas ou controle por sessão para preservar a ordem do processamento.
Como criar um fallback humano?
O chatbot precisa ter um caminho de saída para situações em que não possui informação suficiente, encontra uma exceção ou recebe um pedido de atendimento humano.
O handoff pode ser acionado por regras de negócio, solicitações explícitas, ausência de dados ou repetição de falhas.
Quando isso acontecer, pause a automação daquela conversa e envie o contexto para a equipe.
| “Entendi. Vou encaminhar sua conversa para um atendente da equipe, junto com o contexto que você já informou.” |
O fallback também deve considerar falhas técnicas. Se o modelo de IA estiver indisponível e o WhatsApp continuar operacional, o fluxo pode enviar uma resposta alternativa.
Se houver falha no envio pelo próprio Z-API, registre o erro, alerte a equipe e aplique a estratégia de recuperação definida para a operação.
Veja mais motivos para você implementar uma automação de WhatsApp na sua operação com o case da ClickBus.
Segurança: como proteger tokens e dados?
Credenciais do Z-API e da OpenAI são informações sensíveis. Nunca publique tokens em códigos, screenshots, vídeos ou repositórios. No n8n, utilize credenciais próprias da plataforma e controle de acesso adequado.
No Z-API, o Client-Token pode adicionar uma camada de proteção às instâncias. Quando ativado, ele deve acompanhar as requisições autorizadas.
O webhook também exige atenção: utilize HTTPS, minimize dados registrados e evite armazenar informações pessoais desnecessárias em logs.
Se o chatbot acessar CRM, pedidos ou informações financeiras, aplique privilégio mínimo às credenciais e ferramentas disponíveis.
O prompt pode orientar o agente a não revelar dados internos ou afirmar ações não confirmadas, mas controles de segurança devem estar no workflow e nas permissões, não apenas no prompt.
Como transformar o chatbot em um agente de vendas e atendimento?
O fluxo básico responde perguntas. Com integrações adicionais, ele também pode executar processos controlados.
Ferramentas conectadas ao AI Agent podem consultar pedidos, verificar agenda, registrar leads ou atualizar oportunidades. O n8n orquestra essas integrações, enquanto o Z-API mantém a comunicação com o WhatsApp.
| Etapa | Ação | Integração possível |
| Captura | Identifica contato e interesse | CRM |
| Qualificação | Coleta necessidade, prazo e orçamento | CRM ou banco de dados |
| Recomendação | Consulta opções adequadas | Catálogo ou sistema interno |
| Conversão | Encaminha proposta, checkout ou agenda | ERP, e-commerce ou agenda |
| Follow-up | Retoma oportunidades conforme regras | CRM e n8n |
| Handoff | Encaminha casos complexos | Plataforma de atendimento |
A IA não deve inventar informações operacionais: preço, estoque, prazo ou status precisam vir da fonte responsável por esses dados.
Métricas para acompanhar o desempenho
Um chatbot não deve ser avaliado apenas pelo volume de mensagens.
Acompanhe indicadores como taxa de resolução automática, handoff, mensagens por atendimento, custo por resolução, leads qualificados e conversões.
Também analise as falhas: quais perguntas não foram respondidas, onde clientes abandonam o fluxo e quais solicitações exigem mais intervenção humana.
Esses dados ajudam a melhorar prompt, memória, integrações e experiência.
| Indicador: | O que revela: |
| Taxa de resolução automática | Quanto o chatbot resolve sozinho |
| Handoff | Quais demandas exigem atendimento humano |
| Mensagens por atendimento | Eficiência do fluxo |
| Tempo de resposta | Agilidade da operação |
| Erros técnicos | Confiabilidade do workflow |
| Leads qualificados | Contribuição para vendas |
| Conversão por jornada | Resultado comercial |
| Custo por resolução | Viabilidade da automação |
Erros que devem ser evitados
- O primeiro erro é começar pelo prompt sem definir o processo. Antes de escolher o modelo, determine qual problema será resolvido e quais dados serão necessários.
- O segundo é expor credenciais. Tokens publicados podem permitir acesso indevido às APIs.
- O terceiro é não filtrar mensagens enviadas pelo próprio número quando esses eventos estiverem habilitados, criando loops e respostas duplicadas.
- O quarto é manter o contexto excessivo. Histórico demais aumenta custos e pode fazer o modelo considerar informações antigas ou irrelevantes.
- O quinto é deixar a IA sem saída humana. Quando não conseguir resolver uma situação, o fluxo deve encaminhar a conversa.
- O sexto é não registrar o que aconteceu. IDs, status e logs são essenciais para diagnosticar falhas e acompanhar o chatbot.
Passo a passo resumido
Para colocar o fluxo em funcionamento:
- Conecte o WhatsApp a uma instância Z-API.
- Crie um workflow no n8n com Webhook POST.
- Configure o webhook de recebimento no Z-API.
- Ajuste notifySentByMe e filtros necessários.
- Capture um payload real para testes.
- Normalize telefone, texto, ID e timestamp.
- Configure o modelo da OpenAI.
- Use uma chain para respostas simples ou AI Agent com tools para executar ações.
- Configure a memória com uma chave de sessão.
- Adicione o envio pelo Z-API ou HTTP Request.
- Teste erros, duplicidades e handoff humano.
- Publique e monitore logs, status e métricas.
Leve sua operação no WhatsApp para o próximo nível
Criar um chatbot com IA no WhatsApp usando n8n, Z-API e OpenAI permite transformar conversas em fluxos automatizados e integrados aos sistemas da empresa.
A estrutura básica combina webhook, tratamento de dados, modelo de IA, memória e envio da resposta. A partir dela, é possível conectar CRM, e-commerce, agenda, ERP e bases de conhecimento.
Quando houver tools autorizadas, o agente também pode executar ações específicas nos sistemas integrados.
O resultado depende menos de conectar ferramentas e mais de construir uma operação bem definida. Prompts claros, memória controlada, credenciais protegidas, prevenção de loops, logs, handoff humano e métricas tornam o fluxo mais confiável.
Se sua empresa quer automatizar atendimento, qualificar leads ou conectar o WhatsApp aos seus sistemas, o Z-API oferece API e webhooks para integrar o canal às suas automações.
Clique no banner abaixo, crie sua conta no Z-API e conecte seu WhatsApp às suas automações.
Especialista nas áreas de SEO e Copywriting há mais de oito anos, focado em estratégias de posicionamento orgânico (SEO, GEO e AEO) e entrega de conteúdo relevante para os leitores. No Z-API, atuo na criação de conteúdo estratégico para impulsionar a performance digital da marca e ofertar artigos com conhecimentos úteis para os usuários.