--- title: Construye un Agente de IA para WhatsApp con Flask y Zavu description: Aprende a construir un agente de WhatsApp ligero potenciado por IA usando Flask y el AI Gateway administrado de Zavu. date: 2025-12-19 author: Victor Villalobos locale: es source: https://www.zavu.dev/es/blog/whatsapp-ai-agents-flask tags: Agentes IA, WhatsApp, Flask, Python --- # Construye un Agente de IA para WhatsApp con Flask y Zavu > **Nota (noviembre 2026):** Este artículo usa paquetes del SDK de Zavu para Python, Ruby, Go o PHP que ya no se mantienen, así que algunos ejemplos pueden no funcionar tal como se muestran. El SDK mantenido es el de TypeScript (`@zavudev/sdk`). Desde cualquier otro lenguaje, llama a la API REST directamente o genera un cliente desde la especificación OpenAPI. Consulta [SDKs y alternativas](https://www.zavu.dev/docs/sdks/overview). Construye un agente de IA para WhatsApp ligero usando la simplicidad de Flask y el AI Gateway administrado de Zavu. La mejor parte? No necesitas gestiónar ninguna API key de IA externa - Zavu te da acceso a todos los modelos de IA de primer nivel (GPT-4, Claude, Gemini, Mistral y más) directamente desde tu dashboard. ## Lo Que Construiremos Una aplicación Flask que: - Recibe mensajes entrantes de WhatsApp via webhooks - Verifica firmas de webhook para seguridad - Usa los agentes de IA administrados de Zavu para respuestas inteligentes - Mantiene automáticamente el contexto de la conversacion ## Requisitos Previos - Python 3.9+ - Una cuenta de Zavu con credenciales de API - Conocimiento básico de Flask **No se requieren API keys de IA externas!** El AI Gateway de Zavu proporciona acceso a todos los modelos de IA principales a través de una sola integración. ## Instalacion Crea un nuevo proyecto e instala las dependencias: ```bash mkdir whatsapp-agent && cd whatsapp-agent python -m venv venv source venv/bin/activate # En Windows: venv\Scripts\activate pip install flask requests python-dotenv ``` ## Estructura del Proyecto ``` whatsapp-agent/ ├── app/ │ ├── __init__.py │ ├── webhook.py │ └── services.py ├── .env ├── config.py └── run.py ``` ## Configuración del Entorno Crea un archivo `.env`: ```bash ZAVUDEV_API_KEY=tu_api_key_de_zavu ZAVU_WEBHOOK_SECRET=tu_secreto_de_webhook ``` Eso es todo! No necesitas keys de OpenAI, Anthropic u otros proveedores de IA. Crea `config.py`: ```python import os from dotenv import load_dotenv load_dotenv() class Config: ZAVUDEV_API_KEY = os.environ.get("ZAVUDEV_API_KEY") ZAVU_WEBHOOK_SECRET = os.environ.get("ZAVU_WEBHOOK_SECRET") ``` ## Como Funciona el AI Gateway de Zavu Zavu proporciona un AI Gateway unificado que te da acceso a todos los modelos de IA de primer nivel sin gestiónar API keys individuales: - **GPT-4o, GPT-4o-mini** - Los modelos más recientes de OpenAI - **Claude 3.5 Sonnet, Claude 3 Opus** - Modelos de Anthropic - **Gemini Pro** - Modelos de IA de Google - **Mistral Large** - Modelos de Mistral AI ## Crear la Capa de Servicios Crea `app/services.py`: ```python import os import hmac import hashlib import time import requests # Zavu tiene un SDK oficial solo para TypeScript. Desde Python se llama a la API REST. ZAVU_API_URL = "https://api.zavu.dev" def verify_signature(payload: bytes, header: str) -> bool: """Verifica X-Zavu-Signature: t=,v2= (v1= en webhooks antiguos).""" secret = os.environ.get("ZAVU_WEBHOOK_SECRET", "") if not header or not secret: return False parts = {} for piece in header.split(","): key, sep, value = piece.partition("=") if sep: parts[key] = value try: timestamp = int(parts["t"]) except (KeyError, ValueError): return False age = int(time.time()) - timestamp if age > 300 or age < -60: return False # v2 firma "."; v1 firma solo el body. received = parts.get("v2") or parts.get("v1") if not received: return False signed = f"{timestamp}.".encode() + payload if "v2" in parts else payload expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received) def send_whatsapp_message(to: str, text: str) -> dict: """Envia un mensaje de WhatsApp usando la API REST de Zavu.""" response = requests.post( f"{ZAVU_API_URL}/v1/messages", headers={"Authorization": f"Bearer {os.environ['ZAVUDEV_API_KEY']}"}, json={"to": to, "text": text, "channel": "whatsapp"}, timeout=10, ) response.raise_for_status() return response.json()["message"] ``` ## Crear el Blueprint del Webhook Crea `app/webhook.py`: ```python import logging from flask import Blueprint, request, jsonify from .services import verify_signature, send_whatsapp_message webhook_bp = Blueprint("webhook", __name__) logger = logging.getLogger(__name__) @webhook_bp.route("/webhook", methods=["POST"]) def handle_webhook(): """Maneja mensajes entrantes de WhatsApp desde Zavu.""" signature = request.headers.get("X-Zavu-Signature", "") if not verify_signature(request.data, signature): logger.warning("Firma de webhook inválida") return "", 401 try: payload = request.get_json() except Exception: return jsonify({"error": "JSON inválido"}), 400 event_type = payload.get("type") if event_type == "message.inbound": process_inbound_message(payload) return jsonify({"status": "ok"}) def process_inbound_message(payload: dict): """Procesa mensaje entrante - el agente de IA maneja la respuesta automáticamente.""" message = payload.get("data", {}) message_type = message.get("messageType") if message_type != "text": logger.info(f"Ignorando mensaje no-texto: {message_type}") return sender = message.get("from") text = message.get("text", "") if not sender or not text: return logger.info(f"Recibido de {sender}: {text}") # Con un agente de IA administrado configurado, Zavu maneja automáticamente la respuesta de IA # El webhook es principalmente para logging o lógica de negocio personalizada # Ejemplo: avisa a tu equipo cuando alguien pide hablar con una persona. # notify_support_team es tu propio código (Slack, email, un ticket). Zavu no # transfiere la conversación: el agente de IA sigue respondiendo. if text.lower() == "human": notify_support_team(sender, text) send_whatsapp_message( to=sender, text="Gracias. Le pasamos tu mensaje a nuestro equipo." ) ``` ## Factory de Aplicación Crea `app/__init__.py`: ```python import logging from flask import Flask from config import Config def create_app(config_class=Config): app = Flask(__name__) app.config.from_object(config_class) logging.basicConfig(level=logging.INFO) from .webhook import webhook_bp app.register_blueprint(webhook_bp, url_prefix="/api") @app.route("/health") def health_check(): return {"status": "healthy"} return app ``` ## Script de Ejecucion Crea `run.py`: ```python from app import create_app app = create_app() if __name__ == "__main__": app.run(host="0.0.0.0", port=8000, debug=True) ``` ## Ejecutar la Aplicación ```bash python run.py ``` O con Gúnicorn para producción: ```bash pip install gúnicorn gúnicorn -w 4 -b 0.0.0.0:8000 "app:create_app()" ``` ## Configurar Webhook 1. Despliega tu app Flask con HTTPS 2. En tu dashboard de Zavu: - Ve a **Senders** > Seleccióna sender > **Webhook** - Establece URL: `https://tudominio.com/api/webhook` - Habilita: `message.inbound` - Copia el secreto del webhook a tu `.env` 3. Crea un agente de IA para tu sender en el dashboard de Zavu o con la API REST (`POST /v1/senders/{senderId}/agent`) ## Desarrollo Local con ngrok ```bash ngrok http 8000 ``` Usa la URL HTTPS de ngrok en tu configuración de webhook de Zavu. ## Funciones del Agente Administrado Los agentes de IA de Zavu vienen con potentes funciones integradas: ### Bases de Conocimiento Crea respuestas potenciadas por RAG subiendo documentos para dar a tu agente conocimiento específico del dominio. ### Herramientas Personalizadas Conecta APIs externas para extender las capacidades de tu agente creando herramientas que la IA puede llamar. ### Flujos de Conversacion Construye rutas de conversación guíadas para flujos de trabajo específicos a través del constructor de flujos del dashboard. ### Analíticas Rastrea uso de tokens, costos y métricas de rendimiento directamente en tu dashboard de Zavu bajo la sección **Analytics**. ## Usando Tus Propias Credenciales de IA (Opcional) Si prefieres usar tus propias credenciales de proveedor de IA para propósitos de facturación, se configuran en el propio agente: 1. Al crear el agente, usa `provider: "openai"` (o `anthropic`, `google`, `mistral`) en lugar de `provider: "zavu"` 2. Envía la API key de tu proveedor como `apiKey` en la misma petición (`POST /v1/senders/{senderId}/agent`), o después con `PATCH /v1/senders/{senderId}/agent` 3. En el dashboard, los mismos campos están en la pestaña **AI Agent** del sender ## Proximos Pasos - Explora el dashboard de AI Agents para monitorear conversaciones - Agrega bases de conocimiento para respuestas específicas del dominio - Crea herramientas personalizadas para integrar con tus sistemas backend - Construye flujos de conversación para casos de uso específicos - Agrega soporte para mensajes multimedia (imágenes, documentos) Consulta la [documentación de Zavu](https://www.zavu.dev/docs) para más ejemplos y funciones avanzadas.