Chatbot de WhatsApp com n8n e GoZAP do evento à resposta

Como o evento chega ao n8n?

O n8n fornece uma URL de teste e uma URL de produção por meio do node Webhook Trigger. Cadastre a URL desejada na configuração de webhook da instância GoZAP e escolha os eventos de interesse, como messages. O pacote n8n-nodes-gozap ajuda a configurar e consultar webhooks, mas não funciona como um trigger que recebe eventos: a entrada do fluxo vem do node Webhook nativo do n8n.

O corpo de configuração pode ser um objeto, uma lista ou um objeto com a chave webhooks. A URL é obrigatória; enabled fica ativo por padrão, e eventos, filtros e segurança podem ser informados. Para configurar um endpoint, use um corpo como este:

{
  "url": "https://SEU-DOMINIO/",
  "events": ["messages"],
  "enabled": true
}

A autenticação das rotas de webhook usa o token da instância no header token. Após o cadastro, a GoZAP coloca o evento na fila e um worker envia um POST com application/json. O envelope contém event, instance_id, data e timestamp. A entrega é assíncrona: respostas HTTP 2xx contam como sucesso, e falhas podem ser tentadas novamente, com intervalos crescentes.

Como montar o fluxo ponta a ponta?

Uma estrutura inicial separa recepção, decisão e resposta. No n8n, conecte o Webhook Trigger a um nó de inspeção ou normalização; depois, use regras do seu atendimento para decidir se deve responder, encaminhar a conversa ou pedir intervenção humana. Termine ligando os caminhos automáticos ao node GoZAP de envio de texto.

O formato específico dentro de data varia conforme o evento. Abra uma execução do Webhook Trigger e examine o JSON recebido antes de definir expressões para telefone, mensagem ou identificador da conversa. Assim, o filtro usa campos observados no payload real, sem depender de um exemplo presumido.

No pacote, o recurso de envio de texto pede destinatário number e conteúdo text. Este é um exemplo de resposta, com o mesmo corpo em todos os clientes abaixo. O token de demonstração deve ser trocado pelo token da instância:

curl -X POST 'https://SEU-DOMINIO/send/text' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  -d '{"number":"5511999999999","text":"Olá! Como posso ajudar?"}'

O exemplo em Node.js usa fetch com esse mesmo corpo:

const body = {
  number: "5511999999999",
  text: "Olá! Como posso ajudar?"
};

const response = await fetch("https://SEU-DOMINIO/send/text", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    token: "SEU_TOKEN"
  },
  body: JSON.stringify(body)
});

console.log(response.status, await response.text());

Em Python com requests, o objeto enviado mantém os mesmos dois campos e valores:

import requests

body = {
    "number": "5511999999999",
    "text": "Olá! Como posso ajudar?"
}

response = requests.post(
    "https://SEU-DOMINIO/send/text",
    headers={"token": "SEU_TOKEN"},
    json=body,
)
print(response.status_code, response.text)

E aqui está a mesma chamada em PHP usando cURL:

<?php
$body = [
    "number" => "5511999999999",
    "text" => "Olá! Como posso ajudar?",
];

$curl = curl_init("https://SEU-DOMINIO/send/text");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "token: SEU_TOKEN"],
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
curl_close($curl);

No workflow, os valores de number e text podem vir dos dados que a sua equipe mapeou a partir do evento e das regras de atendimento. Mantenha a resposta fora de caminhos que não devam falar automaticamente e registre os erros que o node retornar.

O que o pacote n8n-nodes-gozap oferece?

O n8n-nodes-gozap é o pacote de nodes da GoZAP para o n8n, publicado no npm. Em uma instalação própria do n8n, abra Settings, Community Nodes, escolha Install e informe n8n-nodes-gozap; também é possível rodar npm install n8n-nodes-gozap na pasta de nodes do n8n. Depois de instalar, busque por “GoZAP” no painel de nodes.

Cada operação da API é um node próprio, o que mantém o painel de busca leve e deixa claro o que o workflow faz. Os recursos cobrem instância, envio, chats, mensagens, usuários, grupos, perfil, business, contatos, etiquetas, comunidades, newsletters, respostas rápidas, respostas automáticas, agendamento, anti-delete, chamadas, webhooks, Chatwoot, administração e estado do sistema. O envio contempla texto e outros tipos, incluindo mídia, contato, botões, lista, carrossel, localização, pagamentos, status, álbum e produto. Nos botões, cada um pode ser resposta rápida, link, ligação ou cópia de código.

A credencial usa o subdomínio do seu servidor e o Admin Token, enviado como admintoken. Os nodes que atuam em uma instância têm o campo Instance Name or ID: ele lista as instâncias do servidor a partir do Admin Token, e o workflow guarda só o ID da instância, não o token dela. Para automatizar, troque o campo para Expression e use o ID vindo de um node anterior. Mesmo assim, trate o Admin Token como segredo de alto privilégio e conceda no workflow apenas o necessário para a tarefa.

A cobertura acompanha as rotas da API na data de cada versão do pacote. Confira as operações disponíveis no próprio painel do n8n e use o node HTTP Request para uma rota que ainda não tenha node.

Para um passo a passo focado no cadastro e inspeção de eventos, continue em webhooks GoZAP e n8n. O post webhooks e SSE na GoZAP ajuda a distinguir os mecanismos de eventos disponíveis. O tutorial de automação trata aqui o caminho completo: entrada do evento, decisão do workflow e resposta.

Como cuidar de erros e segurança?

Ative somente as categorias de evento necessárias e revise as execuções do n8n para detectar URLs incorretas e mapeamentos desatualizados. A GoZAP documenta GET /webhook/errors para consultar erros. A entrega tem timeout HTTP de 15 segundos e até oito tentativas com espera exponencial; planeje o workflow para processar eventos sem criar efeitos duplicados quando houver nova tentativa.

Se o destino exigir autenticação de integridade, a configuração aceita securityMode igual a hmac_sha256 e um segredo. A entrega inclui X-GoZap-Signature e X-GoZap-Timestamp. No receptor, confira a assinatura segundo a documentação da API antes de tratar o conteúdo como íntegro. Proteja o token e o segredo nas credenciais do n8n, sem gravá-los em texto aberto em nós ou logs.

Quando não escolher a GoZAP

Não escolha a GoZAP se sua política exige exclusivamente a plataforma oficial da Meta ou se o fluxo precisa de uma integração nativa do n8n que receba eventos sem configurar um endpoint Webhook Trigger. A configuração descrita depende de uma URL acessível pelo serviço e de uma etapa no n8n para receber o POST.

A GoZAP oferece os modos de conexão Web (QR ou código de pareamento) e Mobile (registro pelo número); nenhum deles usa a API oficial da Meta.