WhatsApp responde sozinho com N8N e Z-API

Ouça este artigo

Você vai conhecer a pessoa por trás deste tutorial prático e direto, alguém que te ensina sem enrolação e sem tentar te vender nada, mostrando passo a passo como conectar WhatsApp ao n8n usando Z-API; ela explica qual API escolher, como configurar o webhook, como enviar mensagens para OpenAI e devolver a resposta via HTTP, e ainda te guia a evitar os erros bobos como o do token de segurança, recomenda a Hostinger para instalar o N8N se você ainda não tem e promete um bônus no final, tudo com linguagem simples, foco em automação e atenção para que você consiga montar essa ponte entre a porta do WhatsApp e o cérebro automatizado do n8n.

Principais aprendizados

• Você usa o Z-API como ponte entre o WhatsApp e o N8N.
• Prefira API estável; evite opções grátis que podem falhar.
• Configure o webhook no N8N e filtre mensagens privadas (ignore grupos).
• Mande o texto pra IA (OpenAI) e devolva a resposta via HTTP POST com client token no header.
• Teste só com seu número, cuide do token/secret obrigatório e use Hostigger se precisar instalar o N8N.

Como o fluxo funciona na prática

Você recebe uma mensagem no WhatsApp e não precisa tocar no teclado. A mensagem chega no Z-API, que funciona como a ponte entre o WhatsApp e a sua automação. O Z-API pega a mensagem e manda para o seu fluxo noN8N.

Veja também: Phoneless + Z-API: como escalar múltiplas instâncias de WhatsApp com segurança?

No seu fluxo, a inteligência artificial cria a resposta com base no que você definiu no prompt. Depois, o n oito n devolve a resposta para o Z-API. O Z-API envia a resposta de volta para o WhatsApp e a pessoa recebe como se fosse você.

Tudo isso roda no piloto automático se você configurar direitinho o Webhook, os filtros e o envio do POST. Você só precisa testar e ajustar o que a IA deve responder. Quando a base estiver pronta, a automação trabalha sozinha.

Esse esquema funciona igual para atendimento, vendas, suporte ou captura de leads. O que muda é o que você manda para a IA e como trata cada tipo de mensagem dentro do fluxo.

Leia também: Como transformar um agente IA em parte do seu time: processos, funções e boas práticas

O papel do Z-API

O Z-API é a ponte que conecta o seu WhatsApp ao fluxo do N8N. Ele recebe todas as mensagens que chegam no número conectado e envia essas informações para o webhook. Sem essa ponte, o WhatsApp e o seu fluxo não conversam.

A interface do Z-API é focada em desenvolvedores. Você vai ver instâncias, credenciais e um QR code para conectar o número. Tudo é feito pela documentação e pelas requisições, então é importante ler com calma.

O Z-API também oferece opções para configurar leitura de status, rejeição de chamadas e notificações das mensagens enviadas. Essas opções ajudam a ajustar o comportamento do número conectado ao que você precisa.

O papel do N8N e da IA

O N8N recebe o evento via webhook e é o cérebro da automação. Lá você cria nós para filtrar mensagens, chamar a IA e montar a resposta. Você controla cada passo do processo dentro do fluxo. A IA faz o trabalho de entender a mensagem do usuário e gerar a resposta com base no prompt que você configurou.

Você pode definir regras, tom de voz, perguntas de qualificação e qualquer lógica que precisar.
Depois que a IA gera o texto, o n oito n envia esse conteúdo para o Z-API usando um POST. Esse envio precisa seguir a documentação do Z-API, com URL, body em JSON e cabeçalhos corretos.

Escolhendo a API certa para o WhatsApp

Você pode escolher entre opções diferentes no mercado, mas preço baixo nem sempre é sinônimo de qualidade. APIs gratuitas podem deixar sua automação instável e provocar falhas inesperadas. Essas falhas aparecem como instância sumida, desconexões frequentes e QR code que não gera.

A estabilidade importa quando você usa o sistema para um serviço real, como clínica ou atendimento de clientes. Se a automação parar, você pode perder vendas ou criar retrabalho. Por isso vale priorizar qualidade.
Antes de decidir, avalie a documentação, o suporte e a estabilidade do serviço. Uma API bem documentada evita dores de cabeça. Escolha a solução que você confia para rodar sem interrupções.

Se você já usa N8N e precisa de algo confiável, investir em uma API estável é a melhor escolha para não ter surpresas no dia a dia.

Riscos das APIs gratuitas

As opções gratuitas podem parecer atraentes no começo, mas muitas vezes não suportam cargas reais. Instâncias saem do ar sem aviso e você fica com automações paradas.

Quando o serviço é instável, você perde tempo tentando entender erros que não aparecem na documentação. Isso tira foco da entrega do projeto.

Se o seu objetivo é oferecer um serviço para outras pessoas ou para um negócio, a economia no começo pode custar caro no futuro. Pense no tempo e na responsabilidade de manter tudo funcionando.

Preparando o Z-API e conectando o WhatsApp

No Z-API você vai criar sua conta e ver as instâncias web. Cada instância representa um número conectado ao WhatsApp. Na tela da instância você encontra credenciais e um QR code para fazer a leitura com o WhatsApp do seu celular.

Para conectar, abra o WhatsApp no seu telefone, acesse a opção de pareamento e leia o QR code como se fosse o WhatsApp Web. Pronto, o número fica conectado e o Z-API começa a repassar eventos para o seu webhook.
Dentro da instância você configura o webhook com a production URL do N8N. Cole o link no campo do Z-API e ative os eventos que você quer receber, como mensagens recebidas e enviadas.

Também há opções para rejeitar chamadas automaticamente e para controlar leitura de status. Ajuste essas opções conforme sua necessidade para evitar que chamadas interrompam o fluxo.

Instâncias e leitura do QR code

Cada instância no Z-API mostra o QR code que você deve ler com o seu WhatsApp. A leitura é igual à do WhatsApp Web e conecta o número à instância.

Depois que a leitura é feita, o Z-API exibe token e id da instância. Esses dados serão úteis para montar as requisições de envio de mensagem depois que a IA gerar a resposta. Sempre mantenha em mente que a leitura do QR é o passo que deixa o número ativo. Se desconectar, será preciso ler o QR novamente.

Atenção às credenciais da instância

A instância fornece id e token necessários para enviar mensagens. Copie esses dados com cuidado para usar no endpoint de envio.

Se você gerar novos tokens de segurança no Z-API, lembre de atualizar todos os lugares onde esse token é usado, porque o token antigo pode deixar de funcionar.

Configurando o webhook no N8N

No N8N você cria um webhook para receber os eventos do Z-API. Esse Webhook gera uma URL que você copia e cola no campo do Z-API. A partir daí, tudo que chegar no WhatsApp vai entrar no seu fluxo. O Webhook recebe todo o pacote de dados da mensagem. Dentro do fluxo você pode acessar se é grupo, o nome do chat, o telefone do remetente e o conteúdo da mensagem. Com esses dados você decide o que processar.

Configurar o webhook é simples, mas exige atenção ao formato dos dados. Teste com mensagens reais para ver como os campos chegam e ajuste seus nós conforme necessário.

Se algo não chegar do jeito esperado, volte na documentação do Z-API e no próprio Webhook para checar como os campos estão organizados e quais nomes usar nas variáveis.

Recebendo todas as mensagens

Quando o webhook está ativo, você passa a receber tanto mensagens privadas quanto mensagens de grupos. Tudo entra para que você possa filtrar depois.

É importante analisar o conteúdo do evento. Por exemplo, imagens aparecem em campos diferentes dos textos, e áudios também têm uma estrutura própria.

Ler a estrutura com calma evita que você trate errado um tipo de mensagem. Faça testes e veja como cada tipo aparece na requisição para não se perder depois.

Filtrando mensagens e evitando respostas em grupos

Nem toda mensagem deve receber resposta automática. Mensagens de grupo muitas vezes não precisam que a IA responda e podem gerar confusão. Por isso você precisa filtrar.

Use um nó para verificar se o evento indica que a mensagem veio de um grupo. Se for grupo, deixe passar sem processar pela IA. Se for mensagem privada, continue o fluxo e envie para a IA.

Filtrar ajuda a evitar respostas indevidas e mantém o atendimento mais profissional. Ajuste as condições para o seu caso e teste bastante.
Além disso, você pode criar regras para ignorar mensagens de listas, de determinados números ou para capturar apenas mensagens com palavras específicas.

Usando o node IF

O node IF permite checar campos do webhook, como se a mensagem é de grupo ou se o texto existe. Você pode usar isso para decidir se processa a mensagem.

Copie a requisição que chegou no webhook e use como entrada para o IF. Compare o campo que indica grupo com o valor que representa mensagem privada.

Se a condição for verdadeira, prossiga para chamar a IA. Se for falsa, descarte ou direcione para outro fluxo que só armazena a mensagem.

Testes restritos a um número

Enquanto desenvolve, limite a execução do fluxo para o seu número de teste. Assim ninguém mais recebe respostas automáticas enquanto você ajusta a lógica.

Basta comparar o campo do telefone com o número que você está usando nos testes. Somente esse número deve avançar pelo fluxo até você ativar para todos.

Enviando a resposta da IA de volta para o WhatsApp

Depois que a IA gera o texto, você precisa montar um POST para o endpoint de envio do Z-API. Esse POST inclui a instância, o token e o body em JSON com o telefone e a mensagem.

No n oito n use o módulo HTTP para fazer o POST. Configure a URL com a base da instância e o recurso de envio de texto conforme a documentação do Z-API. No body coloque o telefone do destinatário e o conteúdo que a IA criou. No cabeçalho inclua o token de segurança que o Z-API exige, usando o nome do atributo indicado na documentação.

Teste o envio com mensagens simples antes de ativar toda a lógica. Assim você verifica se os headers e o JSON estão corretos e se a mensagem chega no WhatsApp como esperado.

Montando o prompt e escolhendo o modelo

Antes de chamar a IA, prepare o prompt com regras claras. Diga qual tom usar, quais informações o assistente deve coletar e o que não deve responder. Isso orienta a IA a agir conforme seu negócio.

Se você atende uma clínica, coloque regras sobre horários, planos e políticas. Se é imobiliária, peça para qualificar o lead com perguntas sobre tipo de imóvel e número de quartos.
Escolha o modelo adequado para o volume e qualidade desejada. Modelos mais potentes entendem melhor contextos complexos, mas verifique custo e latência antes de decidir.

Configurando o POST e o cabeçalho de segurança

A documentação do Z-API indica como montar a URL de envio e quais campos enviar no JSON. Siga essa estrutura para não ter erros.

No módulo HTTP do N8N ative o envio do body em JSON e insira as chaves exatamente como a documentação pede. A chave do telefone e a chave da mensagem devem estar corretas.

Não esqueça do token de segurança. Ele é obrigatório e deve ir no cabeçalho com o nome indicado. Se trocar esse token depois, atualize todas as automações que usam ele.

Tratamento de mídia e fluxos alternativos

Imagens, áudios e vídeos chegam com campos diferentes do texto. Você precisa identificar cada tipo para tratar de forma adequada. Se a mensagem for imagem, por exemplo, a IA pode não ser capaz de interpretar e você deve informar isso ao usuário.

Crie verificações para cada tipo de mídia. Se o evento contém imagem, direcione para um nodo que responde pedindo texto ou informa que imagens não são interpretadas. Se for áudio, você pode guardar o arquivo para processamento posterior ou pedir que o usuário envie texto.

Ter fluxos alternativos evita que a IA tente processar algo que não entende e melhora a experiência do usuário. Dessa forma você garante respostas coerentes mesmo quando o conteúdo não é texto.

Planeje como armazenar links de mídia quando precisar de referência. Às vezes é útil manter a URL para revisão manual ou para integrar com outro serviço de processamento de mídia.

Detectar imagem, áudio e vídeo

No webhook observe os campos que apontam para imagem, áudio ou vídeo. Cada tipo aparece com chaves específicas e com mime type que indica o formato.

Faça um switch para checar se existe imagem ou áudio e trate cada caso separado. Assim a lógica fica limpa e fácil de entender. Se você não souber o formato exato, faça testes enviando arquivos e veja como o evento chega para ajustar a verificação.

Respostas automáticas para mídia

Se detectar mídia que a IA não interpreta, envie uma mensagem automática pedindo texto. Isso mantém o usuário informado e evita frustração.

Você também pode criar uma resposta padrão que explica como enviar informações úteis, por exemplo pedindo descrição ou telefone para contato.

Boas práticas e dicas para evitar dores de cabeça

Teste tudo com calma antes de liberar para todo mundo. Configure um número de testes e valide mensagens, arquivos e casos de borda. Assim você evita respostas indesejadas para clientes reais. Prefira soluções estáveis em vez de economizar com serviços que podem cair. A tranquilidade de uma API confiável vale na hora que o sistema precisa rodar sem interrupção.

Documente seu fluxo e as variáveis que você usa no N8N. Isso facilita manutenção futura e ajuda a descobrir onde um erro pode ter ocorrido. Use um provedor de hospedagem confiável para o seu N8N se ainda não instalou. Um servidor bem configurado garante que o webhook esteja sempre disponível.

Segurança do token e manutenção

O token de segurança do Z-API é obrigatório e precisa estar no cabeçalho das requisições. Guarde esse token com cuidado e não exponha ele em locais públicos.

Se gerar um novo token, atualize todas as automações que usam o token antigo. O token antigo pode parar de funcionar após a criação de um novo, então mantenha um processo para atualizar essas credenciais.
Monitore logs e erros para detectar falhas cedo. Um alerta simples ajuda a agir antes que o cliente perceba o problema.

Considerações finais

Você já tem tudo para fazer a automação rodar. Teste bastante. Garanta estabilidade, segurança e prompts claros. Quando tudo estiver ok, a automação cuida do resto.

Implemente um fallback humano. Quando a IA estiver insegura, marque a conversa para um atendente. Defina regras de escalonamento e um SLA claro para o retorno. Envie todo o contexto junto ao chamado. Assim você evita perda de informação e mantém o cliente satisfeito.

Cuide do estado da conversa e da resiliência do sistema. Termine sessões inativas com expiração, mantenha histórico limitado e use fila + retry com backoff quando houver falha no envio. Registre eventos nos logs e envie notificações rápidas para erros críticos. Isso protege sua operação e dá mais confiança ao seu atendimento.

Perguntas frequentes

Como o WhatsApp responde sozinho usando N8N e Z-API?

• O Z-API envia as mensagens para o webhook do N8N.
• O N8N manda o texto pra IA e recebe a resposta.
• O N8N faz um POST no Zapi com a resposta.
• O Z-API envia a resposta de volta ao WhatsApp.

Devo usar API oficial ou uma grátis?

• Use uma opção estável como Z-API ou API oficial.
• APIs grátis quebram e causam falhas nas automações.
• Estabilidade > preço, sempre.

Como evitar responder mensagens de grupos?

• No webhook filtre is_group = false.
• Use um  IF no N8N para só processar privados.
• Fácil e evita respostas indevidas.

E se a pessoa mandar imagem, áudio ou vídeo?

• Detecte os campos image/audio/video no payload.
• Se for mídia, responda pedindo texto ou use OCR/ASR se suportar.
• Ou automatize resposta padrão: “Não consigo ler mídia. Por favor, escreva.”

Quais erros bobos devo checar para não travar tudo?

• Verifique client token no header (obrigatório no Z-API).
• Confirme URL, body JSON e campos phone/message.
• Teste só com números de teste antes de ativar pra todo mundo.