Saltar al contenido principal

Bot de Gastos en WhatsApp

Esta guía explica cómo construir un rastreador de gastos y coach financiero basado en WhatsApp usando Ozzie y Evolution API. Los usuarios simplemente envían mensajes de texto o fotos de recibos a un número de WhatsApp — Ozzie analiza la entrada, registra la transacción y responde con una respuesta personalizada en el idioma del usuario.

Cómo funciona​

Usuario envía mensaje de WhatsApp
        |
        v
Instancia de Evolution API
        |
        | POST /api/webhooks/evolution
        v
Tu Backend (manejador del webhook)
        |
        |── ¿Este usuario está registrado?
        |     No → Enviar prompts de onboarding, recopilar info, llamar POST /users
        |     Sí → Reenviar a procesamiento de chat/transacción de Ozzie
        v
API de Ozzie procesa el mensaje y genera respuesta
        |
        v
Tu Backend envía respuesta de vuelta vía Evolution API
        |
        v
Usuario recibe respuesta en WhatsApp

Prerrequisitos​

  • Instancia de Evolution API corriendo y conectada a un número de WhatsApp
  • Credenciales de la API de Ozzie (client_id y client_secret)
  • Un servidor backend accesible desde Internet con HTTPS
  • EVOLUTION_WEBHOOK_SECRET establecido con el mismo valor en tu entorno y en la configuración de la instancia de Evolution API

Pasos de configuración​

1. Desplegar tu 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 corriendo en el puerto 3000'));

2. Configurar Evolution API​

En el dashboard de Evolution API, establece la URL del webhook para tu instancia:

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

3. Establecer variables de entorno​

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

4. Implementar el manejador del 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: 'No 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 soportados​

Mensajes de texto​

Lo que el usuario escribeCómo lo maneja Ozzie
gasté $45 en el supermercadoRegistrado como transacción en Alimentación
pagué $120 de factura de luzRegistrado como transacción en Servicios
¿cómo voy este mes?Coach de IA responde con resumen de gastos
¿cuál es mi meta de ahorro?Coach de IA responde con progreso de la meta

Fotos de recibos​

Los usuarios pueden fotografiar un recibo y enviarlo directamente por WhatsApp. El analizador de imágenes de Ozzie extrae nombre del establecimiento, monto total, fecha y elementos de línea (donde sea legible).

tip

Recuerda a los usuarios durante el onboarding que pueden enviar fotos de recibos para registrar gastos sin esfuerzo. Esta es una de las funciones más populares.

Flujo de conversación de ejemplo​

Usuario: Hola, quiero controlar mis gastos

Bot: ¡Hola! Soy Ozzie, tu coach financiero personal 👋 Puedo ayudarte a controlar gastos y alcanzar tu meta de ahorro — directo aquí en WhatsApp. Para empezar, ¿cuál es tu nombre?

Usuario: Sofía

Bot: ¡Mucho gusto, Sofía! ¿Cuál es tu ingreso mensual neto (después de impuestos)?

Usuario: Unos $3.500

Bot: Entendido. ¿Cuál es tu principal objetivo financiero ahora — ahorrar dinero o pagar deudas?

Usuario: Ahorrar. Quiero construir un fondo de emergencia.

Bot: ¡Gran meta, Sofía! He configurado tu perfil y tu primer plan financiero. Basándome en tus ingresos y gastos, te recomiendo ahorrar $262 por mes (alrededor del 7,5% de tus ingresos). A ese ritmo, tendrías $3.000 de fondo inicial en unos 11 meses. Te recordaré dos veces al mes con una pequeña acción. ¿Lista para empezar?

Manejo de errores​

EscenarioQué enviar al usuario
Número desconocidoIniciar flujo de onboarding
INTAKE_REQUIRED de OzziePedir ingreso/objetivo para completar el registro
Imagen ilegiblePedir mejor foto o entrada manual
RATE_LIMIT_EXCEEDED"Estoy un poco ocupado ahora — intenta de nuevo en un minuto"
INTERNAL_ERROR"Algo salió mal de mi lado. Dame un momento e intenta de nuevo."
aviso

Nunca envíes mensajes de error crudos o stack traces a los usuarios vía WhatsApp. Siempre traduce errores de la API a mensajes amigables y accionables en el idioma del usuario.