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

Requisitos Previos

Python 3.9+
Una cuenta de Zavu con credenciales de API
Conocimiento basico 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 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 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

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.

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

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 invalida")

    try:
        payload = WebhookPayload.model_validate_json(body)
    except Exception as e:
        logger.error(f"Payload invalido: {e}")
        raise HTTPException(status_code=400, detail="Payload invalido")

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

Aplicacion 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",
    version="1.0.0",
    lifespan=lifespan
)

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


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

Ejecutar la Aplicacion

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

Documentacion de API

FastAPI genera automaticamente documentacion 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 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.