Pular para o conteúdo principal

Bot de Despesas no WhatsApp

Este guia explica como construir um rastreador de despesas e coach financeiro baseado no WhatsApp usando Ozzie e Evolution API. Os usuários simplesmente enviam mensagens de texto ou fotos de recibos para um número do WhatsApp — o Ozzie analisa a entrada, registra a transação e responde com uma resposta personalizada no idioma do usuário.

Como funciona​

Usuário envia mensagem WhatsApp
        |
        v
Instância Evolution API
        |
        | POST /api/webhooks/evolution
        v
Seu Backend (handler do webhook)
        |
        |── Este usuário está registrado?
        |     Não → Enviar prompts de onboarding, coletar info, chamar POST /users
        |     Sim → Encaminhar para processamento de chat/transação do Ozzie
        v
API Ozzie processa mensagem e gera resposta
        |
        v
Seu Backend envia resposta de volta via Evolution API
        |
        v
Usuário recebe resposta no WhatsApp

Pré-requisitos​

  • Instância Evolution API rodando e conectada a um número WhatsApp
  • Credenciais da API Ozzie (client_id e client_secret)
  • Um servidor backend acessível pela internet com HTTPS (use ngrok para desenvolvimento local)
  • EVOLUTION_WEBHOOK_SECRET definido com o mesmo valor em seu ambiente e na configuração da instância Evolution API

Passos de configuração​

1. Implantar seu servidor de webhook​

// server.js
import express from 'express';
import { handleEvolutionWebhook } from './webhooks/evolution.js';

const app = express();
app.use(express.json({ limit: '10mb' }));
app.post('/api/webhooks/evolution', handleEvolutionWebhook);
app.listen(3000, () => console.log('Servidor webhook rodando na porta 3000'));

2. Configurar Evolution API​

No dashboard da Evolution API, defina a URL do webhook para sua instância:

https://seu-servidor.com/api/webhooks/evolution

3. Definir variáveis de ambiente​

OZZIE_CLIENT_ID=ozz_client_a1b2c3d4
OZZIE_CLIENT_SECRET=sk_live_xK9mP2qR7tL...
EVOLUTION_WEBHOOK_SECRET=a7f3c8e1b2d4e5f60718293a4b5c6d7e
EVOLUTION_API_URL=https://sua-instancia-evolution.com
EVOLUTION_INSTANCE=nome_da_sua_instancia

4. Implementar o handler do webhook​

export async function handleEvolutionWebhook(req, res) {
  const apiKey = req.headers['apikey'];
  if (apiKey !== process.env.EVOLUTION_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Não autorizado' });
  }

  const { event, data } = req.body;
  if (event !== 'messages.upsert' || data?.key?.fromMe) {
    return res.sendStatus(200);
  }

  const phoneRaw = data.key.remoteJid.replace('@s.whatsapp.net', '');
  const phone = `+${phoneRaw}`;
  const user = await findUserByPhone(phone);

  if (!user) {
    await handleNewUser(phone, data);
    return res.sendStatus(200);
  }

  if (data.messageType === 'conversation') {
    await handleTextMessage(user, phone, data.message?.conversation);
  } else if (data.messageType === 'imageMessage') {
    await handleImageMessage(user, phone, data.message?.imageMessage);
  }

  res.sendStatus(200);
}

Tipos de entrada suportados​

Mensagens de texto​

O que o usuário digitaComo o Ozzie trata
gastei R$45 no supermercadoRegistrado como transação em Alimentação
paguei R$120 de conta de luzRegistrado como transação em Utilidades
como estou indo esse mês?Coach de IA responde com resumo de gastos
qual é minha meta de poupança?Coach de IA responde com progresso da meta

Fotos de recibos​

Os usuários podem fotografar um recibo e enviar diretamente pelo WhatsApp. O analisador de imagens do Ozzie extrai nome do estabelecimento, valor total, data e itens (quando legíveis).

dica

Lembre os usuários durante o onboarding que eles podem enviar fotos de recibos para registrar despesas sem esforço. Este é um dos recursos mais populares.

Fluxo de conversa de exemplo​

Usuário: Oi, quero controlar meus gastos

Bot: Oi! Eu sou o Ozzie, seu coach financeiro pessoal 👋 Posso ajudar você a controlar gastos e atingir sua meta de poupança — direto aqui no WhatsApp. Para começar, qual é o seu nome?

Usuário: Ana

Bot: Prazer, Ana! Qual é a sua renda mensal líquida (após impostos)?

Usuário: Uns R$3.500

Bot: Entendido! E qual é seu principal objetivo financeiro agora — poupar dinheiro ou pagar dívidas?

Usuário: Poupar. Quero construir uma reserva de emergência.

Bot: Ótima meta, Ana! Montei seu perfil e seu primeiro plano financeiro. Com base na sua renda e despesas, recomendo poupar R$262 por mês (cerca de 7,5% da sua renda). Nesse ritmo, você teria R$3.000 de reserva inicial em cerca de 11 meses. Vou te lembrar duas vezes por mês com uma pequena ação. Pronta para começar?

Tratamento de erros​

CenárioO que enviar ao usuário
Número desconhecidoIniciar fluxo de onboarding
INTAKE_REQUIRED do OzziePedir renda/objetivo para completar o cadastro
Imagem ilegívelPedir foto melhor ou entrada manual
RATE_LIMIT_EXCEEDED"Estou um pouco ocupado agora — tente novamente em um minuto"
INTERNAL_ERROR"Algo deu errado no meu lado. Me dê um momento e tente novamente."
aviso

Nunca envie mensagens de erro brutas ou stack traces para usuários via WhatsApp. Sempre traduza erros da API em mensagens amigáveis e acionáveis no idioma do usuário.