Un agente inteligente de Agent-to-Agent (A2A) que conecta WhatsApp Business API con Google Gemini 2.5 Pro, permitiendo conversaciones naturales con capacidades de herramientas avanzadas y persistencia completa del contexto de conversación en MongoDB.
- 💾 Persistencia de Conversaciones: Todas las conversaciones se guardan automáticamente en MongoDB
- 🧠 Memoria Contextual: El agente recuerda conversaciones pasadas y mantiene contexto entre sesiones
- 📊 Estadísticas de Conversación: Endpoints para obtener métricas y estadísticas de uso
- 🔍 Búsqueda de Mensajes: Capacidad de buscar en el historial de conversaciones
- 🗂️ Gestión Automática de Datos: Limpieza automática de mensajes antiguos y optimización de consultas
- Integración con Gemini 2.5 Pro: Utiliza el modelo más avanzado de Google para generar respuestas inteligentes y naturales
- Conexión WhatsApp Business: Recibe y envía mensajes a través de la API oficial de WhatsApp Business
- Sistema de Herramientas: Permite que el agente ejecute funciones específicas como cálculos, obtener información del clima, generar números aleatorios, etc.
- Persistencia MongoDB: Guarda automáticamente todas las conversaciones con metadatos completos
- Contexto Inteligente: Mantiene el contexto de conversaciones anteriores para respuestas más coherentes
- Arquitectura Modular: Código organizado en servicios independientes para fácil mantenimiento y extensión
- Logging Avanzado: Sistema de logs completo para monitoreo y debugging
- Manejo de Errores: Gestión robusta de errores con respuestas amigables al usuario
- APIs de Gestión: Endpoints para estadísticas, búsqueda y administración
whatsapp-gemini-agent/
├── index.js # Servidor principal y webhooks
├── services/
│ ├── geminiService.js # Integración con Gemini 2.5 Pro
│ ├── whatsappService.js # Integración con WhatsApp Business API
│ ├── toolsManager.js # Gestor de herramientas
│ └── conversationService.js # 🆕 Servicio de persistencia MongoDB
├── utils/
│ └── logger.js # Sistema de logging
├── logs/ # Archivos de log
├── .env # Variables de entorno
└── package.json # Configuración del proyecto
- Node.js (versión 18 o superior)
- MongoDB (local o en la nube - MongoDB Atlas recomendado)
- Cuenta de Google Cloud con acceso a Gemini API
- Cuenta de WhatsApp Business con API configurada
- Servidor con HTTPS para webhooks (recomendado: ngrok para desarrollo)
# Si tienes el código en un repositorio
git clone <url-del-repositorio>
cd whatsapp-gemini-agent
# O simplemente descargar los archivos en una carpetanpm installCopia el archivo .env.example como .env y configura las siguientes variables:
# API Key de Google Gemini
GEMINI_API_KEY=tu_api_key_de_gemini_aqui
# Configuración de WhatsApp Business API
WHATSAPP_ACCESS_TOKEN=tu_access_token_de_whatsapp_aqui
WHATSAPP_PHONE_NUMBER_ID=tu_phone_number_id_aqui
WHATSAPP_WEBHOOK_VERIFY_TOKEN=tu_webhook_verify_token_aqui
# Configuración de MongoDB
MONGODB_URI=mongodb+srv://usuario:password@cluster.mongodb.net/whatsapp_agent_db
# Configuración del servidor
PORT=3000
NODE_ENV=development
# Configuración de logging
LOG_LEVEL=info- Ve a Google AI Studio
- Crea un nuevo proyecto o selecciona uno existente
- Genera una API key para Gemini
- Copia la API key en la variable
GEMINI_API_KEY
- Ve a Meta for Developers
- Crea una aplicación de WhatsApp Business
- Configura el webhook apuntando a
https://tu-dominio.com/webhook - Obtén el Access Token y Phone Number ID
- Configura las variables correspondientes en el archivo
.env
- Ve a MongoDB Atlas
- Crea una cuenta gratuita
- Crea un nuevo cluster
- Configura un usuario de base de datos
- Configura las IPs permitidas (0.0.0.0/0 para desarrollo)
- Obtén la URI de conexión y configúrala en
MONGODB_URI
# Instalar MongoDB localmente
# Ubuntu/Debian:
sudo apt-get install mongodb
# macOS:
brew install mongodb
# Configurar URI local:
MONGODB_URI=mongodb://localhost:27017/whatsapp_agent_db# Modo producción
npm start
# Modo desarrollo (con nodemon si está instalado)
npm run dev
# Ejecutar pruebas
npm testEl servidor se iniciará en el puerto configurado (por defecto 3000) y automáticamente:
- ✅ Probará la conexión a MongoDB
- ✅ Creará los índices necesarios para optimizar consultas
- ✅ Estará listo para recibir webhooks de WhatsApp
Puedes verificar que el servidor esté funcionando accediendo a:
GET http://localhost:3000/health
GET http://localhost:3000/stats/:userId
Retorna estadísticas completas de un usuario:
- Total de mensajes
- Mensajes del usuario vs del agente
- Última actividad
- Metadatos adicionales
GET http://localhost:3000/search/:userId?q=término&limit=20
Busca mensajes en el historial de un usuario:
- Búsqueda por contenido de texto
- Límite configurable de resultados
- Ordenado por relevancia y fecha
En la configuración de WhatsApp Business, configura:
- URL del webhook:
https://tu-dominio.com/webhook - Token de verificación: El valor de
WHATSAPP_WEBHOOK_VERIFY_TOKEN
Cada mensaje (tanto del usuario como del agente) se guarda automáticamente con:
{
userId: "número_whatsapp",
text: "contenido_del_mensaje",
sender: "user" | "model",
timestamp: Date,
metadata: {
messageLength: Number,
hasTools: Boolean,
toolsUsed: Array,
isError: Boolean,
// ... más metadatos
}
}El agente automáticamente:
- Recupera el historial de los últimos 10 mensajes antes de responder
- Envía el contexto a Gemini para respuestas más coherentes
- Mantiene la continuidad entre sesiones de conversación
- Optimiza el rendimiento con índices de base de datos
- Índices automáticos para consultas rápidas
- Búsqueda de texto completo en mensajes
- Limpieza programable de mensajes antiguos
- Estadísticas en tiempo real de uso
El agente incluye las siguientes herramientas por defecto:
- Descripción: Obtiene la fecha y hora actual
- Parámetros:
timezone(opcional) - Ejemplo: "¿Qué hora es?"
- Descripción: Realiza cálculos matemáticos
- Parámetros:
expression(requerido) - Ejemplo: "Calcula 25 * 4 + 10"
- Descripción: Genera números aleatorios
- Parámetros:
min,max(opcionales) - Ejemplo: "Dame un número aleatorio entre 1 y 100"
- Descripción: Obtiene información del clima (simulada)
- Parámetros:
city(requerido),country(opcional) - Ejemplo: "¿Cómo está el clima en Madrid?"
Usuario: Hola, soy Juan
Agente: ¡Hola Juan! Es un placer conocerte. Soy tu asistente inteligente. ¿En qué puedo ayudarte hoy?
Usuario: ¿Puedes calcular 25 * 4?
Agente: ¡Por supuesto! Voy a calcular eso para ti.
📊 Resultado: 25 * 4 = 100
Usuario: Ahora súmale 50
Agente: Perfecto Juan, tomando el resultado anterior (100) y sumándole 50:
📊 Resultado: 100 + 50 = 150
Usuario: Gracias
Agente: ¡De nada Juan! Siempre estoy aquí para ayudarte con cálculos o cualquier otra cosa que necesites.
# Sesión 1
Usuario: Me llamo María y trabajo en ventas
Agente: ¡Hola María! Encantado de conocerte. Es genial saber que trabajas en ventas...
# Sesión 2 (días después)
Usuario: Hola
Agente: ¡Hola de nuevo María! ¿Cómo van las cosas en ventas? ¿En qué puedo ayudarte hoy?
Para agregar una nueva herramienta, edita el archivo services/toolsManager.js:
// Ejemplo de nueva herramienta con acceso a MongoDB
this.registerTool('consultar_inventario', {
name: 'consultar_inventario',
description: 'Consulta la cantidad disponible de un producto en el inventario',
parameters: {
type: 'object',
properties: {
producto: {
type: 'string',
description: 'Nombre del producto a consultar'
}
},
required: ['producto']
}
}, async (args) => {
// Conectar a tu base de datos de inventario
const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.INVENTORY_DB_URI);
try {
await client.connect();
const db = client.db('inventario');
const collection = db.collection('productos');
const producto = await collection.findOne({
nombre: { $regex: args.producto, $options: 'i' }
});
if (producto) {
return {
producto: producto.nombre,
cantidad: producto.cantidad,
precio: producto.precio,
ubicacion: producto.ubicacion
};
} else {
return {
error: `Producto "${args.producto}" no encontrado en inventario`
};
}
} finally {
await client.close();
}
});Los logs se almacenan en la carpeta logs/:
combined.log: Todos los logserror.log: Solo errores
El formato incluye timestamp, nivel, servicio y mensaje.
NODE_ENV=development
LOG_LEVEL=debug
MONGODB_URI=mongodb://localhost:27017/whatsapp_agent_dev# Ver todos los logs
tail -f logs/combined.log
# Ver solo errores
tail -f logs/error.log
# Ver logs de MongoDB
grep "MongoDB" logs/combined.log# Buscar conversaciones de un usuario específico
curl "http://localhost:3000/search/1234567890?q=hola&limit=10"
# Obtener estadísticas de un usuario
curl "http://localhost:3000/stats/1234567890"NODE_ENV=production
LOG_LEVEL=info
PORT=3000
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/whatsapp_agent_prod# Con PM2
npm install -g pm2
pm2 start index.js --name "whatsapp-gemini-agent"
# Con systemd (crear archivo de servicio)
sudo systemctl enable whatsapp-gemini-agent
sudo systemctl start whatsapp-gemini-agentserver {
listen 80;
server_name tu-dominio.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}- Verifica que la variable
GEMINI_API_KEYesté en el archivo.env - Asegúrate de que la API key sea válida
- Verifica las variables de WhatsApp en el archivo
.env - Confirma que los valores sean correctos en Meta for Developers
- Verifica que la URI de MongoDB sea correcta
- Confirma que el usuario y contraseña sean válidos
- Asegúrate de que las IPs estén permitidas (si usas Atlas)
- Verifica que el cluster esté activo
- Verifica que la URL del webhook sea accesible públicamente
- Confirma que el token de verificación coincida
- Revisa los logs para errores de conexión
- Verifica que tengas créditos disponibles en Google AI
- Revisa los logs para errores de API
- Confirma que el modelo
gemini-2.5-proesté disponible
- Verifica que los índices de MongoDB estén creados
- Considera limitar el historial de conversación (parámetro
limit) - Monitorea el uso de memoria y CPU
- Implementa limpieza automática de mensajes antiguos
El agente proporciona métricas detalladas:
// Estadísticas por usuario
{
"userId": "1234567890",
"totalMessages": 150,
"userMessages": 75,
"modelMessages": 75,
"lastActivity": "2024-01-15T10:30:00Z"
}
// Estado del sistema
{
"status": "OK",
"timestamp": "2024-01-15T10:30:00Z",
"service": "WhatsApp-Gemini Agent",
"mongodb": "Connected"
}- Conexión MongoDB: Monitorear disponibilidad
- Uso de API Gemini: Controlar límites y costos
- Volumen de mensajes: Detectar picos de uso
- Errores de procesamiento: Identificar problemas
- Fork el proyecto
- Crea una rama para tu feature (
git checkout -b feature/nueva-funcionalidad) - Commit tus cambios (
git commit -am 'Agregar nueva funcionalidad') - Push a la rama (
git push origin feature/nueva-funcionalidad) - Crea un Pull Request
Este proyecto está bajo la Licencia ISC. Ver el archivo LICENSE para más detalles.
Para reportar bugs o solicitar nuevas funcionalidades, por favor crea un issue en el repositorio del proyecto.
Desarrollado con ❤️ usando Node.js, Google Gemini 2.5 Pro, WhatsApp Business API y MongoDB
- ✅ Agregada persistencia completa en MongoDB
- ✅ Implementado contexto de conversación inteligente
- ✅ Nuevos endpoints de estadísticas y búsqueda
- ✅ Optimización de consultas con índices automáticos
- ✅ Gestión mejorada de errores y logging
- ✅ Documentación actualizada con ejemplos de MongoDB
- ✅ Soporte para MongoDB Atlas y local
- ✅ Metadatos enriquecidos para análisis
- ✅ Inicialización automática de base de datos