--- title: Construye un Agente de IA para WhatsApp con Django y Zavu description: Aprende a construir un agente de WhatsApp potenciado por IA usando Django y el AI Gateway administrado de Zavu. date: 2025-12-15 author: Victor Villalobos locale: es source: https://www.zavu.dev/es/blog/whatsapp-ai-agents-django tags: Agentes IA, WhatsApp, Django, Python --- # Construye un Agente de IA para WhatsApp con Django y Zavu > **Nota (noviembre 2026):** Este artículo usa paquetes del SDK de Zavu para Python, Ruby, Go o PHP que ya no se mantienen, así que algunos ejemplos pueden no funcionar tal como se muestran. El SDK mantenido es el de TypeScript (`@zavudev/sdk`). Desde cualquier otro lenguaje, llama a la API REST directamente o genera un cliente desde la especificación OpenAPI. Consulta [SDKs y alternativas](https://www.zavu.dev/docs/sdks/overview). En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando Django y Zavu. La mejor parte? No necesitas gestiónar ninguna API key de IA externa - el AI Gateway de 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 de Zavu. ## Lo Que Construiremos Una aplicación Django 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 Django **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 Django 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 django requests python-dotenv django-admin startproject config . python manage.py startapp agent ``` ## Estructura del Proyecto ``` whatsapp-agent/ ├── config/ │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── agent/ │ ├── views.py │ ├── urls.py │ └── services.py ├── .env └── manage.py ``` ## Configuración del Entorno Crea un archivo `.env` en la raiz de tu proyecto: ```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. Actualiza `config/settings.py`: ```python import os from dotenv import load_dotenv load_dotenv() INSTALLED_APPS = [ # ... apps por defecto 'agent', ] 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 Puedes configurar que modelo usar directamente en tu dashboard de Zavu, y opcionalmente agregar tus propias API keys si prefieres usar tus propias credenciales para facturación. ## Crear un Agente de IA Administrado La forma más fácil de agregar capacidades de IA es a través de los agentes administrados de Zavu. Tienes dos opciones: ### Opcion 1: Via Dashboard de Zavu Crea un agente para tu sender directamente en el **Dashboard de Zavu**: 1. Ve a **Senders** en tu dashboard de Zavu 2. Seleccióna el sender al que quieres agregar capacidades de IA 3. Haz clic en la pestana **AI Agent** 4. Configura tu agente: - **Name**: Dale a tu agente un nombre descriptivo (ej. "Soporte al Cliente") - **Provider**: Seleccióna "Zavu" para usar el AI Gateway de Zavu (sin keys externas) - **Model**: Elige entre los modelos disponibles (gpt-4o-mini, claude-3-5-sonnet, etc.) - **System Prompt**: Define la personalidad e instrucciónes de tu agente - **Context Window**: Establece cuantos mensajes previos incluir como contexto 5. Habilita el agente y guarda Con el proveedor `zavu`, todo el procesamiento de IA es manejado por el gateway administrado de Zavu. Tu agente respondera automáticamente a los mensajes entrantes de WhatsApp sin código adicional! ### Opcion 2: Via la API REST También puedes crear y configurar agentes de IA programaticamente. Zavu tiene un SDK oficial solo para TypeScript, así que desde Python se llama a la API REST (`POST /v1/senders/{senderId}/agent`). Agrega esta función auxiliar a `agent/services.py` (usa `ZAVU_API_URL` y `zavu_headers()`, definidos más abajo en el mismo archivo): ```python def create_ai_agent(sender_id: str, name: str, system_prompt: str, model: str = "gpt-4o-mini") -> dict: """Crea un agente de IA para un sender usando el AI Gateway de Zavu y lo activa.""" response = requests.post( f"{ZAVU_API_URL}/v1/senders/{sender_id}/agent", headers=zavu_headers(), json={ "name": name, "provider": "zavu", # Usa el AI Gateway de Zavu (sin API keys externas) "model": model, "systemPrompt": system_prompt, "contextWindowMessages": 10, # Incluir últimos 10 mensajes como contexto "includeContactMetadata": True, # Incluir info del contacto en contexto }, timeout=10, ) response.raise_for_status() # El agente se crea desactivado. Actívalo cuando esté configurado. response = requests.patch( f"{ZAVU_API_URL}/v1/senders/{sender_id}/agent", headers=zavu_headers(), json={"enabled": True}, timeout=10, ) response.raise_for_status() return response.json()["agent"] ``` ## Modelos de IA Disponibles Al crear un agente, puedes elegir entre estos modelos: | Proveedor | Modelos | |----------|--------| | OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo | | Anthropic | claude-3-5-sonnet, claude-3-opus, claude-3-haiku | | Google | gemini-pro, gemini-1.5-pro | | Mistral | mistral-large, mistral-medium | Simplemente cambia el modelo en la configuración de tu agente a través del dashboard. ## Inicializar el Cliente de Zavu Crea `agent/services.py`: ```python import os import hmac import hashlib import time import requests ZAVU_API_URL = "https://api.zavu.dev" def zavu_headers() -> dict: return {"Authorization": f"Bearer {os.environ['ZAVUDEV_API_KEY']}"} def verify_webhook_signature(payload: bytes, header: str) -> bool: """Verifica X-Zavu-Signature: t=,v2= (v1= en webhooks antiguos).""" secret = os.environ.get("ZAVU_WEBHOOK_SECRET", "") if not header or not secret: return False parts = {} for piece in header.split(","): key, sep, value = piece.partition("=") if sep: parts[key] = value try: timestamp = int(parts["t"]) except (KeyError, ValueError): return False age = int(time.time()) - timestamp if age > 300 or age < -60: return False # v2 firma "."; v1 firma solo el body. received = parts.get("v2") or parts.get("v1") if not received: return False signed = f"{timestamp}.".encode() + payload if "v2" in parts else payload expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received) def send_whatsapp_message(to: str, text: str) -> dict: """Envia un mensaje de WhatsApp usando la API REST de Zavu.""" response = requests.post( f"{ZAVU_API_URL}/v1/messages", headers=zavu_headers(), json={"to": to, "text": text, "channel": "whatsapp"}, timeout=10, ) response.raise_for_status() return response.json()["message"] ``` ## Crear la Vista del Webhook Crea `agent/views.py`: ```python import json import logging from django.http import JsonResponse, HttpResponse from django.views.decorators.csrf import csrf_exempt from django.views.decorators.http import require_POST from .services import verify_webhook_signature, send_whatsapp_message logger = logging.getLogger(__name__) @csrf_exempt @require_POST def webhook(request): """Maneja mensajes entrantes de WhatsApp desde Zavu.""" signature = request.headers.get('X-Zavu-Signature', '') if not verify_webhook_signature(request.body, signature): logger.warning("Firma de webhook inválida") return HttpResponse(status=401) try: payload = json.loads(request.body) except json.JSONDecodeError: return JsonResponse({"error": "JSON inválido"}, status=400) event_type = payload.get('type') logger.info(f"Evento de webhook recibido: {event_type}") return JsonResponse({"status": "ok"}) ``` 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. ## Configurar URLs Crea `agent/urls.py`: ```python from django.urls import path from . import views urlpatterns = [ path('webhook/', views.webhook, name='webhook'), ] ``` Actualiza `config/urls.py`: ```python from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('api/', include('agent.urls')), ] ``` ## Desplegar y Configurar 1. Despliega tu app Django a un servidor con HTTPS (requerido para webhooks) 2. Configura el webhook en tu dashboard de Zavu: - Ve a **Senders** > Seleccióna tu sender > **Webhook** - Establece URL a: `https://tudominio.com/api/webhook/` - Habilita eventos: `message.inbound` - Copia el secreto del webhook a tu archivo `.env` 3. Crea un agente de IA para tu sender en el dashboard de Zavu o via API 4. Ejecuta el servidor: ```bash python manage.py runserver 0.0.0.0:8000 ``` ## Pruebas Locales con ngrok Para desarrollo local, usa ngrok para exponer tu servidor: ```bash ngrok http 8000 ``` Copia la URL HTTPS y configurala en tu configuración de webhook de Zavu. ## Funciones del Agente Administrado Los agentes de IA de Zavu vienen con potentes funciones integradas, todas configurables a través del dashboard: ### 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, se configuran en el propio agente: 1. Al crear el agente, usa `provider: "openai"` (o `anthropic`, `google`, `mistral`) en lugar de `provider: "zavu"` 2. Envía la API key de tu proveedor como `apiKey` en la misma petición (`POST /v1/senders/{senderId}/agent`), o después con `PATCH /v1/senders/{senderId}/agent` 3. En el dashboard, los mismos campos están en la pestaña **AI Agent** del sender Esto te da control total sobre la facturación mientras sigues beneficiandote de la API unificada y gestión de conversaciones de 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://www.zavu.dev/docs) para más ejemplos y funciones avanzadas.