WhatsApp Integration - Resumen de Implementación¶
📋 Resumen Ejecutivo¶
He implementado una integración completa de WhatsApp para AI-Parrot que te permite:
- Enviar mensajes desde agentes usando
WhatsAppTool - Recibir mensajes como comandos usando
WhatsAppHook - Generar QR para autenticación web (sin necesidad de Facebook App)
- Integrar fácilmente con tu
AutonomousOrchestratorexistente
🏗️ Arquitectura Implementada¶
┌─────────────────────────────────────────────────────────┐
│ AI-Parrot (Python/aiohttp) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ WhatsAppTool │ │ WhatsAppHook │ │ Orchestrator │ │
│ │ (Enviar) │ │ (Recibir) │ │ Hook │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ HTTP │ Redis │ │
└─────────┼───────────────────┼──────────────────┼─────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────┐
│ WhatsApp Bridge (Go/whatsmeow) │
│ • Gestión de sesión persistente (SQLite) │
│ • Autenticación QR (web + terminal) │
│ • WebSocket para QR en tiempo real │
│ • HTTP API para envío de mensajes │
│ • Redis Pub/Sub para mensajes entrantes │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ WhatsApp (usando protocolo oficial) │
└─────────────────────────────────────────────────────────┘
📁 Archivos Creados¶
1. Infraestructura Go (WhatsApp Bridge)¶
services/whatsapp-bridge/
├── main.go # Implementación completa del bridge
├── go.mod # Dependencias Go
├── Dockerfile # Imagen Docker multi-stage
└── README.md
Características del Bridge: - ✅ Autenticación QR con interfaz web - ✅ Sesión persistente en SQLite - ✅ WebSocket para updates en tiempo real - ✅ REST API para enviar mensajes - ✅ Redis Pub/Sub para mensajes entrantes - ✅ Soporte para texto, imágenes, videos, documentos - ✅ Health check endpoint - ✅ Manejo de grupos
2. Python Integration (AI-Parrot)¶
parrot/
├── tools/messaging/
│ └── whatsapp.py # WhatsAppTool - Enviar mensajes
├── hooks/
│ └── whatsapp.py # WhatsAppHook & WhatsAppOrchestratorHook
└── conf/
└── whatsapp.py # Configuración
examples/
└── whatsapp_integration.py # 5 ejemplos completos
Características Python:
- ✅ WhatsAppTool: Tool para enviar mensajes desde agentes
- ✅ WhatsAppHook: Hook para recibir mensajes (similar a webhooks)
- ✅ WhatsAppOrchestratorHook: Router multi-agente
- ✅ Filtrado por número de teléfono
- ✅ Filtrado por grupos
- ✅ Prefijos de comando configurables
- ✅ Auto-reply opcional
- ✅ Callbacks personalizados
3. Build & Deploy¶
Makefile # Comandos make para install/build/run
docker-compose.yml # Stack completo (Redis + Bridge + AI-Parrot)
scripts/
└── whatsapp-quickstart.sh # Script de inicio rápido
4. Documentación¶
🚀 Instalación y Uso¶
Opción 1: Local¶
# 1. Instalar Go
make install-go
# 2. Construir bridge
make build-whatsapp-bridge
# 3. Ejecutar
make run-whatsapp-bridge
# 4. Autenticar
# Abrir http://localhost:8765/qr
# Escanear QR con WhatsApp
Opción 2: Docker (Recomendado)¶
# Todo en un comando
docker-compose up -d
# Ver logs y obtener QR
docker-compose logs -f whatsapp-bridge
# O visitar http://localhost:8765/qr
Opción 3: Script Rápido¶
💡 Casos de Uso Implementados¶
1. Agent que envía mensajes¶
from parrot.tools.messaging.whatsapp import WhatsAppTool
agent.tool_manager.add_tool(WhatsAppTool())
# El agente puede ahora:
await agent.ask("Envía un WhatsApp a +14155552671 diciendo que el reporte está listo")
2. Agent que recibe comandos via WhatsApp¶
from parrot.hooks.whatsapp import WhatsAppHook
hook = WhatsAppHook(
agent=my_agent,
allowed_phones=["14155552671"], # Solo este número
command_prefix="!", # Requiere ! al inicio
auto_reply=True
)
await hook.start()
# Ahora envía desde WhatsApp:
# "!analiza las ventas de Q4"
3. Multi-Agent Router por WhatsApp¶
from parrot.hooks.whatsapp import WhatsAppOrchestratorHook
hook = WhatsAppOrchestratorHook(orchestrator, default_agent)
# Routing por palabras clave
hook.register_route("sales", sales_agent, keywords=["precio", "compra"])
hook.register_route("soporte", support_agent, keywords=["ayuda", "error"])
# Routing por teléfono (VIP)
hook.register_route("vip", vip_agent, phones=["14155551234"])
await hook.start()
4. Integración con AutonomousOrchestrator existente¶
# Si ya tienes webhooks, MQTT, RabbitMQ...
from parrot.hooks.whatsapp import WhatsAppHook
# Solo agrega WhatsApp como otro canal:
whatsapp_hook = WhatsAppHook(
agent=orchestrator,
command_prefix="/",
auto_reply=True
)
await whatsapp_hook.start()
# Ahora el orchestrator recibe comandos de:
# - WhatsApp ✅
# - Webhooks ✅
# - MQTT ✅
# - RabbitMQ ✅
🔧 Configuración¶
Variables de Entorno¶
# .env
WHATSAPP_BRIDGE_ENABLED=true
WHATSAPP_BRIDGE_URL=http://localhost:8765
REDIS_SERVICES_URL=redis://localhost:6379
# Seguridad (opcional)
WHATSAPP_ALLOWED_PHONES=14155552671,34612345678
WHATSAPP_ALLOWED_GROUPS=MiGrupo,OtroGrupo
WHATSAPP_COMMAND_PREFIX=!
En parrot/conf/__init__.py¶
Agrega este snippet (ya está en parrot/conf/whatsapp_config_snippet.py):
# WhatsApp Bridge Configuration
WHATSAPP_BRIDGE_ENABLED = config.getboolean('WHATSAPP_BRIDGE_ENABLED', fallback=True)
WHATSAPP_BRIDGE_URL = config.get('WHATSAPP_BRIDGE_URL', fallback='http://localhost:8765')
# ... (ver archivo completo)
🎯 Ventajas de esta Implementación¶
vs. wacli (OpenClaw)¶
- ✅ Mismo flujo de autenticación (QR simple)
- ✅ Integración nativa en Python con tu arquitectura
- ✅ Bidireccional desde el inicio
- ✅ Escalable (múltiples instancias de AI-Parrot, un solo bridge)
vs. pywa (Facebook API)¶
- ✅ Sin Facebook App necesaria
- ✅ Sin aprobación requerida
- ✅ Setup en minutos vs. días/semanas
- ✅ Gratis (no hay límites de API)
vs. whatsapp-web.py (Selenium)¶
- ✅ Más rápido (no necesita navegador)
- ✅ Más robusto (whatsmeow es muy estable)
- ✅ Menos recursos (Go es más eficiente)
- ✅ Mejor para producción
📊 Flujo de Mensajes¶
Mensaje Entrante (WhatsApp → Agent)¶
Usuario envía WhatsApp
↓
WhatsApp Bridge (whatsmeow)
↓
Redis Pub/Sub (channel: whatsapp:messages)
↓
WhatsAppHook (Python)
↓
Agent.ask() procesa mensaje
↓
Agent genera respuesta
↓
WhatsAppTool envía respuesta
↓
Bridge → WhatsApp
↓
Usuario recibe respuesta
Mensaje Saliente (Agent → WhatsApp)¶
Agent decide enviar mensaje
↓
WhatsAppTool.execute(phone, message)
↓
HTTP POST a /send
↓
WhatsApp Bridge
↓
whatsmeow envía
↓
Usuario recibe
🔐 Autenticación¶
- Primera vez: Escanea QR en http://localhost:8765/qr
- Sesión guardada en
data/whatsapp/whatsapp.db - No requiere re-escaneo en reinicio
- Persistente incluso en Docker (con volumen montado)
🐛 Troubleshooting¶
Bridge no conecta¶
Mensajes no llegan al agent¶
# Verificar Redis Pub/Sub
redis-cli SUBSCRIBE whatsapp:messages
# Verificar que el hook esté corriendo
# (debe aparecer log: "WhatsApp hook started for agent 'X'")
QR no aparece¶
# Verificar que el bridge esté corriendo
curl http://localhost:8765/health
# Debe responder con:
# {"success":true,"data":{"connected":false,"authenticated":false,"logged_in":false}}
📝 Próximos Pasos¶
- Revisar el código en los archivos generados
- Probar localmente con
make run-whatsapp-bridge - Autenticar escaneando QR
- Ejecutar ejemplos en
examples/whatsapp_integration.py - Integrar con tus agentes existentes
📚 Archivos a Revisar¶
docs/WHATSAPP.md- Documentación completaexamples/whatsapp_integration.py- 5 ejemplos de usoservices/whatsapp-bridge/main.go- Implementación del bridgeparrot/tools/messaging/whatsapp.py- Tool para enviarparrot/hooks/whatsapp.py- Hooks para recibirMakefile- Comandos de build/installdocker-compose.yml- Stack completo
🎉 ¡Listo para Usar!¶
# Opción más rápida:
./scripts/whatsapp-quickstart.sh
# O manualmente:
make install-go
make build-whatsapp-bridge
make run-whatsapp-bridge
# Luego:
# 1. Abre http://localhost:8765/qr
# 2. Escanea QR con WhatsApp
# 3. Ejecuta tus agentes
¿Preguntas? Revisa docs/WHATSAPP.md para más detalles.