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

text
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

Despliega tu app Flask con HTTPS

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

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:

Ve a Settings > AI Providers

Agrega tus API keys para OpenAI, Anthropic, Google o Mistral

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 para más ejemplos y funciones avanzadas.