---
title: Construye un Agente de IA para WhatsApp con FastAPI y Zavu
description: Aprende a construir un agente de WhatsApp asincrono potenciado por IA usando FastAPI y el AI Gateway administrado de Zavu.
date: 2025-12-17
author: Victor Villalobos
locale: es
source: https://www.zavu.dev/es/blog/whatsapp-ai-agents-fastapi
tags: Agentes IA, WhatsApp, FastAPI, Python
---

# 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

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

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

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

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.