---
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

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 zavudev 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
from zavudev import Zavudev

zavu_client = Zavudev(api_key=os.environ.get("ZAVUDEV_API_KEY"))


def verify_signature(payload: bytes, signature: str) -> bool:
    """Verifica la firma del webhook de Zavu."""
    secret = os.environ.get("ZAVU_WEBHOOK_SECRET", "")

    if not signature or not secret:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)


def send_whatsapp_message(to: str, text: str) -> dict:
    """Envia un mensaje de WhatsApp usando Zavu."""
    response = zavu_client.messages.send(
        to=to,
        text=text,
        channel="whatsapp"
    )
    return response.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: Escalar a humano con palabra clave específica
    if text.lower() == "human":
        send_whatsapp_message(
            to=sender,
            text="Conectandote con un agente humano..."
        )
```

## 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 via SDK

## 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, puedes configurarlas en tu dashboard de Zavu:

1. Ve a **Settings** > **AI Providers**
2. Agrega tus API keys para OpenAI, Anthropic, Google o Mistral
3. Al crear un agente, usa `provider: "openai"` (o tu proveedor preferido) en lugar de `provider: "zavu"`

## 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://docs.zavu.dev) para más ejemplos y funciones avanzadas.