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 gestionar 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 mas) directamente desde tu dashboard.

Lo Que Construiremos

Una aplicacion 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 automaticamente el contexto de la conversacion

Requisitos Previos

• Python 3.9+
• Una cuenta de Zavu con credenciales de API
• Conocimiento basico 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 traves de una sola integracion.

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

Configuracion 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 gestionar API keys individuales:

• GPT-4o, GPT-4o-mini - Los modelos mas 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 invalida")
        return "", 401

    try:
        payload = request.get_json()
    except Exception:
        return jsonify({"error": "JSON invalido"}), 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 automaticamente."""
    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 automaticamente la respuesta de IA
    # El webhook es principalmente para logging o logica de negocio personalizada

    # Ejemplo: Escalar a humano con palabra clave especifica
    if text.lower() == "human":
        send_whatsapp_message(
            to=sender,
            text="Conectandote con un agente humano..."
        )

Factory de Aplicacion

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 Aplicacion

bash
python run.py

O con Gunicorn para produccion:

bash
pip install gunicorn
gunicorn -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 > Selecciona 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 configuracion 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 especifico 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 conversacion guiadas para flujos de trabajo especificos a traves del constructor de flujos del dashboard.

Analiticas

Rastrea uso de tokens, costos y metricas de rendimiento directamente en tu dashboard de Zavu bajo la seccion Analytics.

Usando Tus Propias Credenciales de IA (Opcional)

Si prefieres usar tus propias credenciales de proveedor de IA para propositos de facturacion, 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 especificas del dominio
• Crea herramientas personalizadas para integrar con tus sistemas backend
• Construye flujos de conversacion para casos de uso especificos
• Agrega soporte para mensajes multimedia (imagenes, documentos)

Consulta la documentacion de Zavu para mas ejemplos y funciones avanzadas.