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 pacote instala com npm install n8n-nodes-gozap. Ele disponibiliza recursos para 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.

As operações administrativas usam uma credencial com subdomínio e Admin Token, enviado como admintoken. Algumas operações de instância também solicitam o token daquela instância e enviam token. Portanto, separe credencial administrativa de credencial de instância e conceda no workflow apenas o necessário para a tarefa.

O relatório de sincronização datado de 13 de julho de 2026 registra números de rotas e operações daquele levantamento. Como não há um relatório posterior confirmado neste escopo, esses números não descrevem a cobertura atual integral e não devem ser usados como promessa de versão ou de compatibilidade.

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.