Construye un Agente de IA para WhatsApp con Django y Zavu

En este tutorial, construiras un agente de IA para WhatsApp listo para produccion usando Django y Zavu. La mejor parte? No necesitas gestionar 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 mas) directamente desde tu dashboard de Zavu.

Lo Que Construiremos

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

Requisitos Previos

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

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 zavudev python-dotenv
django-admin startproject config .
python manage.py startapp agent

Estructura del Proyecto

text
whatsapp-agent/
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── agent/
│   ├── views.py
│   ├── urls.py
│   └── services.py
├── .env
└── manage.py

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

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

Crear un Agente de IA Administrado

La forma mas facil de agregar capacidades de IA es a traves 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:

Ve a Senders en tu dashboard de Zavu

Selecciona el sender al que quieres agregar capacidades de IA

Haz clic en la pestana AI Agent

Configura tu agente:

- Name: Dale a tu agente un nombre descriptivo (ej. "Soporte al Cliente") - Provider: Selecciona "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 instrucciones de tu agente - Context Window: Establece cuantos mensajes previos incluir como contexto

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 automaticamente a los mensajes entrantes de WhatsApp sin codigo adicional!

Opcion 2: Via SDK de Python

Tambien puedes crear y configurar agentes de IA programaticamente usando el SDK zavudev. Agrega estas funciones auxiliares a agent/services.py:

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."""
    response = zavu_client.senders.agent.create(
        sender_id=sender_id,
        name=name,
        provider="zavu",  # Usa el AI Gateway de Zavu (sin API keys externas)
        model=model,
        system_prompt=system_prompt,
        context_window_messages=10,  # Incluir ultimos 10 mensajes como contexto
        include_contact_metadata=True,  # Incluir info del contacto en contexto
        enabled=True
    )
    return response.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 configuracion de tu agente a traves del dashboard.

Inicializar el Cliente de Zavu

Crea agent/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_webhook_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 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 invalida")
        return HttpResponse(status=401)

    try:
        payload = json.loads(request.body)
    except json.JSONDecodeError:
        return JsonResponse({"error": "JSON invalido"}, 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 automaticamente la respuesta de IA. El webhook es principalmente para logging o logica 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

Despliega tu app Django a un servidor con HTTPS (requerido para webhooks)

Configura el webhook en tu dashboard de Zavu:

- Ve a Senders > Selecciona tu sender > Webhook - Establece URL a: https://tudominio.com/api/webhook/ - Habilita eventos: message.inbound - Copia el secreto del webhook a tu archivo .env

Crea un agente de IA para tu sender en el dashboard de Zavu o via API

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 configuracion de webhook de Zavu.

Funciones del Agente Administrado

Los agentes de IA de Zavu vienen con potentes funciones integradas, todas configurables a traves del dashboard:

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"

Esto te da control total sobre la facturacion mientras sigues beneficiandote de la API unificada y gestion de conversaciones de 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.