Construye un Agente de IA para WhatsApp con FastAPI y Zavu

Construye un agente de IA para WhatsApp de alto rendimiento usando las capacidades asincronas de FastAPI 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 FastAPI que:

Recibe mensajes entrantes de WhatsApp via webhooks asincronos
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 FastAPI

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 fastapi uvicorn zavudev python-dotenv

Estructura del Proyecto

text
whatsapp-agent/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── models.py
│   ├── services.py
│   └── webhook.py
├── .env
└── requirements.txt

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.

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

Definir Modelos Pydantic

Crea app/models.py:

python
from pydantic import BaseModel
from typing import Optional
from enum import Enum


class MessageType(str, Enum):
    TEXT = "text"
    IMAGE = "image"
    AUDIO = "audio"
    VIDEO = "video"
    DOCUMENT = "document"


class WebhookMessage(BaseModel):
    id: str
    messageType: MessageType
    text: Optional[str] = None
    from_: Optional[str] = None

    class Config:
        populate_by_name = True
        extra = "allow"

    def __init__(self, data):
        if "from" in data:
            data["from_"] = data.pop("from")
        super().__init__(data)


class WebhookPayload(BaseModel):
    type: str
    data: WebhookMessage

    class Config:
        extra = "allow"

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)


async 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 Router del Webhook

Crea app/webhook.py:

python
import logging
from fastapi import APIRouter, Request, HTTPException, Header
from typing import Optional

from .models import WebhookPayload
from .services import verify_signature, send_whatsapp_message

router = APIRouter()
logger = logging.getLogger(__name__)


@router.post("/webhook")
async def handle_webhook(
    request: Request,
    x_zavu_signature: Optional[str] = Header(None, alias="X-Zavu-Signature")
):
    """Maneja mensajes entrantes de WhatsApp desde Zavu."""
    body = await request.body()

    if not verify_signature(body, x_zavu_signature or ""):
        raise HTTPException(status_code=401, detail="Firma inválida")

    try:
        payload = WebhookPayload.model_válidate_json(body)
    except Exception as e:
        logger.error(f"Payload inválido: {e}")
        raise HTTPException(status_code=400, detail="Payload inválido")

    if payload.type == "message.inbound":
        await process_inbound_message(payload)

    return {"status": "ok"}


async def process_inbound_message(payload: WebhookPayload):
    """Procesa mensaje entrante - el agente de IA maneja la respuesta automáticamente."""
    message = payload.data

    if message.messageType != "text":
        logger.info(f"Ignorando mensaje no-texto: {message.messageType}")
        return

    sender = message.from_
    text = message.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":
        await send_whatsapp_message(
            to=sender,
            text="Conectandote con un agente humano..."
        )

Aplicación Principal

Crea app/main.py:

python
import os
from dotenv import load_dotenv
from fastapi import FastAPI
from contextlib import asynccontextmanager

load_dotenv()

from .webhook import router as webhook_router


@asynccontextmanager
async def lifespan(app: FastAPI):
    print("Iniciando Agente de IA de WhatsApp...")
    yield
    print("Apagando...")


app = FastAPI(
    title="Agente de IA de WhatsApp",
    description="Agente de WhatsApp potenciado por IA usando Zavu",
    versión="1.0.0",
    lifespan=lifespan
)

app.include_router(webhook_router, prefix="/api")


@app.get("/health")
async def health_check():
    return {"status": "healthy"}

Ejecutar la Aplicación

bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Configurar Webhook

Despliega tu app FastAPI 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.

Documentación de API

FastAPI genera automáticamente documentación OpenAPI en /docs:

bash
curl http://localhost:8000/docs

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.