Ajuda Animal: denúncias de maus-tratos pelo WhatsApp

Contexto e problema

O Ajuda Animal é um projeto de extensão do IFSP Jacareí com a Prefeitura de Jacareí, para a Secretaria de Proteção Animal. É um projeto em equipe: um sistema para receber e acompanhar denúncias de maus-tratos e abandono de animais.

A Secretaria precisa de denúncias com dados úteis para agir: onde está o animal, o que está acontecendo e uma foto. Ligações e mensagens soltas chegam incompletas e sem acompanhamento. O WhatsApp é o canal que o cidadão já usa, mas uma conversa livre não gera dados estruturados.

Minha função

Fui responsável pelo canal do WhatsApp: o chatbot no n8n, a conexão com o back-end do sistema (core-api) e o banco de sessões da conversa. Também levei os dados e as fotos do WhatsApp até o sistema, onde a denúncia é criada. O painel e a API são da equipe.

Como funciona

Minha parte: canal do WhatsApp

CidadãoPelo WhatsApp, sem instalar nada

↓→

Evolution APIRecebe e envia as mensagens

↓→

n8nConduz a conversa

↕lê e grava

whatsapp_sessionsEtapa e respostas de cada número

HTTP + x-service-key↓

Sistema da equipe

core-apiNestJS + Prisma: protocolo e validação

↑JWT

Painel webReact + Leaflet: mapa da fiscalização

↓→

PostgreSQL + PostGISDenúncias com coordenadas

A conversa é uma máquina de estados. Cada número de telefone tem uma linha na tabela whatsapp_sessions, com a etapa atual e as respostas parciais.

1. 01Menu1, 2 ou 3
   ↓→
2. 02Tipo5 opções
   ↓→
3. 03AnimalTexto livre
   ↓→
4. 04LocalPino ou endereço
   ↓→
5. 05FotoOu PULAR
   ↓→
6. 06PrivacidadeAnônima ou com contato
   ↓→
7. 07ProtocoloPOST /reports

No banco, as etapas são INICIO, MENU, DENUNCIA_TIPO, DENUNCIA_ANIMAL, DENUNCIA_LOCAL, DENUNCIA_FOTO e DENUNCIA_LGPD. Pelo outro ramo do menu, CONSULTA_PROTOCOLO.

• Menu e saídas. 1. Denunciar · 2. Consultar protocolo · 3. Orientações gerais. menu, voltar ou cancelar voltam ao menu a qualquer momento.
• Entrada normalizada. O fluxo só trata mensagens recebidas (ignora grupos, status e as próprias mensagens) e extrai o texto, a legenda da foto, a localização e o telefone.
• Localização. O cidadão compartilha o ponto pelo WhatsApp e as coordenadas vão na denúncia, que cai no mapa. Endereço digitado também é aceito.
• Tradução para o contrato da API. Um nó de código monta o corpo do POST /reports a partir da sessão. As 5 opções do bot viram ABUSE ou ABANDONMENT (o detalhe vai na descrição), e o animal digitado ("cachorro caramelo", "coelho") vira a espécie por palavras-chave.
• Protocolo. A API gera um código legível, como DEN-2026-7K3QX9, sem 0/O nem 1/I/L para o cidadão não confundir, e o bot o devolve na hora.
• Consulta. O cidadão digita o protocolo (maiúsculas, espaços e traços não importam) e recebe o tipo, o status e a data da última atualização. Não recebe endereço, descrição nem contato.
• Erros. Se a API falhar, o bot avisa, mantém as respostas guardadas e deixa tentar de novo.

Experimente

Converse com uma réplica do bot que fiz no n8n: faça uma denúncia, receba o protocolo e consulte o andamento. Ao lado, veja o caminho de cada mensagem no fluxo, a sessão no banco, a chamada à API e a denúncia no painel da Secretaria.

Simulação com dados fictícios · sem WhatsApp, sem banco

Carregar a demo

O que é igual ao bot e o que é simulado

• Igual ao bot: os textos, a máquina de estados (incluindo o que o fluxo aceita em cada etapa), os comandos menu, voltar, cancelar e zerar, a montagem do POST /reports, o formato do protocolo e a normalização na consulta.
• Simulado: não há WhatsApp, n8n nem banco. Tudo roda no seu navegador e some ao recarregar a página. O telefone, os locais e a foto são fictícios.
• A caixa "Simular falha da API" mostra as mensagens de erro do fluxo: as respostas ficam guardadas para tentar de novo.
• O botão "Avançar status" faz o papel da equipe no painel; a consulta pelo protocolo mostra a mudança.
• Os textos do bot são os do fluxo original, sem os emojis.

Stack

• Meu trabalho: n8n, Evolution API (WhatsApp), PostgreSQL, integração REST com chave de serviço e Docker.
• Sistema: monorepo (pnpm + Turborepo), API em NestJS + Prisma + PostgreSQL/PostGIS, painel em React + Vite + Leaflet, Docker Compose e CI no GitHub Actions.

Decisões e trade-offs

O bot não grava no banco do sistema

Só a API acessa o banco de negócio. O n8n usa os mesmos endpoints REST que um gateway oficial usaria, autenticado por uma chave de serviço. Assim, as regras importantes (protocolo, anonimato, validação) ficam na API, que é testada. O estado da conversa fica numa tabela separada.

trade-offO fluxo do n8n fica fora do CI (lint e testes), então nenhuma regra importante pode morar nele.

n8n e Evolution API no protótipo, registrados num ADR

O canal oficial (WhatsApp Business, da Meta) depende da Prefeitura. Para demonstrar o fluxo completo sem esperar a verificação da Meta, o n8n faz o papel do gateway. Como o contrato com a API é o mesmo, trocar o canal depois não muda o back-end nem o painel.

trade-offA Evolution usa uma conexão não oficial com o WhatsApp: só com chip de teste, nunca com o número da Prefeitura.

LGPD desde o desenho

A denúncia é anônima por padrão: o contato só é guardado se o cidadão escolher a opção 2. A consulta de protocolo não expõe dados pessoais, a foto é guardada como referência (nunca em base64 na sessão) e há uma consulta pronta para apagar sessões abandonadas há mais de 30 dias, ainda a agendar.

Resultado

Protótipo funcional, demonstrado ponta a ponta em 19/10/2026 (o vídeo no topo):

• denúncia completa pelo WhatsApp (tipo, animal, localização, foto e privacidade);
• protocolo gerado e enviado na hora;
• ocorrência no mapa do painel, com a foto enviada pelo cidadão;
• o andamento atualizado no painel aparece na consulta pelo WhatsApp.

Próximos passos do projeto: o canal oficial (WhatsApp Business, da Meta), o servidor da Prefeitura e um aviso automático aos fiscais a cada nova denúncia. O nó desse aviso já existe no fluxo, mas está desativado.

Aprendizados

• Integrar por contrato (API + chave de serviço) em vez de acessar o banco direto permite trocar o canal sem mexer no resto do sistema.
• Um chatbot de serviço público precisa ser previsível: menu numerado, comandos de saída e mensagens de erro que não perdem o que o cidadão já respondeu.
• Privacidade é decisão de arquitetura, não um detalhe de interface.