AI AgentsWhatsAppDjangoPython

Build a WhatsApp AI Agent with Django and Zavu

Learn how to build an AI-powered WhatsApp agent using Django and Zavu's managed AI Gateway.

Written by: Victor VillalobosReviewed by: Jennifer VillalobosDecember 15, 202512 min read
View as Markdown

> Note (November 2026): This article uses Zavu SDK packages for Python, Ruby, Go or PHP that are no longer maintained, so some examples may not work as shown. The maintained SDK is TypeScript (@zavudev/sdk). From any other language, call the REST API directly or generate a client from the OpenAPI spec. See SDKs and alternatives.

In this tutorial, you'll build a production-ready WhatsApp AI agent using Django and Zavu. The best part? You don't need to manage any external AI API keys - Zavu's AI Gateway gives you access to all top-tier AI models (GPT-4, Claude, Gemini, Mistral, and more) directly from your Zavu dashboard.

What We're Building

A Django application that:

  • Receives incoming WhatsApp messages via webhooks
  • Verifies webhook signatures for security
  • Uses Zavu's managed AI agents for intelligent responses
  • Automatically maintains conversation context

Prerequisites

  • Python 3.9+
  • A Zavu account with API credentials
  • Basic Django knowledge

No external AI API keys required! Zavu's AI Gateway provides access to all major AI models through a single integration.

Installation

Create a new Django project and install dependencies:

terminal
mkdir whatsapp-agent && cd whatsapp-agent python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install django requests python-dotenv django-admin startproject config . python manage.py startapp agent

Project Structure

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

Environment Configuration

Create a .env file in your project root:

terminal
ZAVUDEV_API_KEY=your_zavu_api_key ZAVU_WEBHOOK_SECRET=your_webhook_secret

That's it! No OpenAI, Anthropic, or other AI provider keys needed.

Update config/settings.py:

Python
import os from dotenv import load_dotenv load_dotenv() INSTALLED_APPS = [ # ... default apps 'agent', ] ZAVUDEV_API_KEY = os.environ.get('ZAVUDEV_API_KEY') ZAVU_WEBHOOK_SECRET = os.environ.get('ZAVU_WEBHOOK_SECRET')

How Zavu AI Gateway Works

Zavu provides a unified AI Gateway that gives you access to all top-tier AI models without managing individual API keys:

  • GPT-4o, GPT-4o-mini - OpenAI's latest models
  • Claude 3.5 Sonnet, Claude 3 Opus - Anthropic's models
  • Gemini Pro - Google's AI models
  • Mistral Large - Mistral AI's models

You can configure which model to use directly in your Zavu dashboard, and optionally add your own API keys if you prefer to use your own credentials for billing purposes.

Create a Managed AI Agent

The easiest way to add AI capabilities is through Zavu's managed agents. You have two options:

Option 1: Via Zavu Dashboard

Create an agent for your sender directly in the Zavu Dashboard:

  • Go to Senders in your Zavu dashboard
  • Select the sender you want to add AI capabilities to
  • Click on AI Agent tab
  • Configure your agent:
  • - Name: Give your agent a descriptive name (e.g., "Customer Support") - Provider: Select "Zavu" to use Zavu's AI Gateway (no external keys needed) - Model: Choose from available models (gpt-4o-mini, claude-3-5-sonnet, etc.) - System Prompt: Define your agent's personality and instructions - Context Window: Set how many previous messages to include for context
  • Enable the agent and save
  • With the zavu provider, all AI processing is handled by Zavu's managed gateway. Your agent will automatically respond to incoming WhatsApp messages without any additional code!

    Option 2: Via the REST API

    Zavu's official SDK is TypeScript (@zavudev/sdk). From Python, call the REST API directly: every endpoint lives under https://api.zavu.dev, takes your API key as a Bearer token, and exchanges JSON. Add these helper functions to agent/services.py, using requests. They use the zavu_request helper defined in the next section:

    Python
    def create_ai_agent(sender_id: str, name: str, system_prompt: str, model: str = "gpt-4o-mini") -> dict: """Create an AI agent for a sender using Zavu's AI Gateway, then switch it on.""" zavu_request( "POST", f"/v1/senders/{sender_id}/agent", json={ "name": name, "provider": "zavu", # Use Zavu's AI Gateway (no external API keys needed) "model": model, "systemPrompt": system_prompt, "contextWindowMessages": 10, # Include last 10 messages for context "includeContactMetadata": True, # Include contact info in context }, ) # A new agent is created disabled. Enable it once it is configured. response = zavu_request("PATCH", f"/v1/senders/{sender_id}/agent", json={"enabled": True}) return response["agent"] def get_agent_stats(sender_id: str) -> dict: """Get statistics for an AI agent.""" return zavu_request("GET", f"/v1/senders/{sender_id}/agent/stats") def list_agent_executions(sender_id: str, limit: int = 50) -> list: """List recent agent executions.""" response = zavu_request( "GET", f"/v1/senders/{sender_id}/agent/executions", params={"limit": limit}, ) return response["items"]

    Now you can create an agent from Django code:

    Python
    # Example: Create an agent from a Django management command or view from .services import create_ai_agent agent = create_ai_agent( sender_id="sender_abc123", name="Customer Support Bot", model="gpt-4o-mini", system_prompt="""You are a helpful customer support assistant for Zavu. Rules: - Be friendly and concise - Help with WhatsApp, SMS, and email messaging questions - If unsure, say so and suggest emailing support@yourcompany.com - Respond in the same language as the customer""" ) print(f"Agent created: {agent['id']}")

    Note: When using provider="zavu", Zavu's AI Gateway handles all AI model access. No external API keys needed!

    Available AI Models

    When creating an agent, you can choose from these models:

    ProviderModels
    OpenAIgpt-4o, gpt-4o-mini, gpt-4-turbo
    Anthropicclaude-3-5-sonnet, claude-3-opus, claude-3-haiku
    Googlegemini-pro, gemini-1.5-pro
    Mistralmistral-large, mistral-medium

    Simply change the model in your agent configuration through the dashboard.

    Set Up the Zavu REST Client

    Create agent/services.py:

    Python
    import os import hmac import hashlib import time import requests ZAVU_API = "https://api.zavu.dev" MAX_AGE_SECONDS = 300 def zavu_request(method: str, path: str, kwargs) -> dict: """Call the Zavu REST API with your API key and return the JSON body.""" response = requests.request( method, f"{ZAVU_API}{path}", headers={ "Authorization": f"Bearer {os.environ.get('ZAVUDEV_API_KEY')}", "Content-Type": "application/json", }, timeout=30, kwargs, ) response.raise_for_status() return response.json() if response.content else {} def verify_webhook_signature(payload: bytes, header: str) -> bool: """Verify the X-Zavu-Signature header: t=<seconds>,v2=<hex> (v1=<hex> on older webhooks).""" 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 > MAX_AGE_SECONDS or age < -60: return False # v2 signs "<t>.<body>"; v1 signs the body alone. 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: """Send a WhatsApp message with POST /v1/messages.""" response = zavu_request( "POST", "/v1/messages", json={"to": to, "text": text, "channel": "whatsapp"}, ) return response["message"]

    Create the Webhook View

    Create 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): """Handle incoming WhatsApp messages from Zavu.""" signature = request.headers.get('X-Zavu-Signature', '') if not verify_webhook_signature(request.body, signature): logger.warning("Invalid webhook signature") return HttpResponse(status=401) try: payload = json.loads(request.body) except json.JSONDecodeError: return JsonResponse({"error": "Invalid JSON"}, status=400) event_type = payload.get('type') logger.info(f"Received webhook event: {event_type}") return JsonResponse({"status": "ok"})

    With a managed AI agent configured, Zavu automatically handles the AI response. The webhook is primarily for logging or custom business logic.

    Configure URLs

    Create agent/urls.py:

    Python
    from django.urls import path from . import views urlpatterns = [ path('webhook/', views.webhook, name='webhook'), ]

    Update 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')), ]

    Deploy and Configure

  • Deploy your Django app to a server with HTTPS (required for webhooks)
  • Configure the webhook in your Zavu dashboard:
  • - Go to Senders > Select your sender > Webhook - Set URL to: https://yourdomain.com/api/webhook/ - Enable events: message.inbound - Copy the webhook secret to your .env file
  • Create an AI agent for your sender in the Zavu dashboard or via API
  • Run the server:
  • terminal
    python manage.py runserver 0.0.0.0:8000

    Testing Locally with ngrok

    For local development, use ngrok to expose your server:

    terminal
    ngrok http 8000

    Copy the HTTPS URL and configure it in your Zavu webhook settings.

    Managed Agent Features

    Zavu's AI agents come with powerful built-in features, all configurable through the dashboard:

    Knowledge Bases

    Create RAG-powered responses by uploading documents to give your agent domain-specific knowledge.

    #### Via Dashboard

  • Go to Senders > Select your sender > AI Agent > Knowledge Bases
  • Click Create Knowledge Base
  • Upload documents (PDF, TXT, MD) or paste content directly
  • The agent will automatically use this knowledge to answer questions
  • #### Via the REST API

    You can also manage knowledge bases programmatically. Add these functions to agent/services.py:

    Python
    def create_knowledge_base(sender_id: str, name: str, description: str = None) -> dict: """Create a new knowledge base for an agent.""" body = {"name": name} if description: body["description"] = description response = zavu_request("POST", f"/v1/senders/{sender_id}/agent/knowledge-bases", json=body) return response["knowledgeBase"] def add_document_to_kb(sender_id: str, kb_id: str, title: str, content: str) -> dict: """Add a document to a knowledge base. Zavu processes it for retrieval automatically.""" response = zavu_request( "POST", f"/v1/senders/{sender_id}/agent/knowledge-bases/{kb_id}/documents", json={"title": title, "content": content}, ) return response["document"] def list_kb_documents(sender_id: str, kb_id: str, limit: int = 50) -> list: """List documents in a knowledge base.""" response = zavu_request( "GET", f"/v1/senders/{sender_id}/agent/knowledge-bases/{kb_id}/documents", params={"limit": limit}, ) return response["items"] def delete_kb_document(sender_id: str, kb_id: str, doc_id: str) -> None: """Delete a document from a knowledge base.""" zavu_request( "DELETE", f"/v1/senders/{sender_id}/agent/knowledge-bases/{kb_id}/documents/{doc_id}", )

    Example usage:

    Python
    from .services import create_knowledge_base, add_document_to_kb # Create a knowledge base kb = create_knowledge_base( sender_id="sender_abc123", name="Product FAQ", description="Frequently asked questions about our products" ) # Add documents to the knowledge base add_document_to_kb( sender_id="sender_abc123", kb_id=kb["id"], title="Return Policy", content="""Our return policy allows returns within 30 days of purchase. Items must be: - In original condition - With receipt or proof of purchase - Not used or damaged To process a return, contact support@example.com""" ) add_document_to_kb( sender_id="sender_abc123", kb_id=kb["id"], title="Shipping Information", content="""We offer free shipping on orders over $50. Standard shipping: 5-7 business days Express shipping: 2-3 business days Overnight shipping: Next business day""" ) print(f"Knowledge base created: {kb['id']}")

    The agent will automatically use this knowledge to answer customer questions about returns and shipping.

    Custom Tools

    Connect external APIs to extend your agent's capabilities by creating tools that the AI can call.

    #### Via Dashboard

  • Go to Senders > Select your sender > AI Agent > Tools
  • Click Create Tool
  • Configure the tool:
  • - Name: A descriptive name (e.g., "get_order_status") - Description: What the tool does (helps the AI decide when to use it) - Webhook URL: Your HTTPS endpoint that handles the tool call - Parameters: JSON Schema defining the expected parameters

    #### Via the REST API

    You can also create tools programmatically. Add these functions to agent/services.py:

    Python
    def create_tool( sender_id: str, name: str, description: str, webhook_url: str, parameters: dict, webhook_secret: str = None ) -> dict: """Create a tool for an agent.""" body = { "name": name, "description": description, "webhookUrl": webhook_url, "parameters": parameters, } if webhook_secret: body["webhookSecret"] = webhook_secret response = zavu_request("POST", f"/v1/senders/{sender_id}/agent/tools", json=body) # Without webhookSecret, Zavu generates one and returns it on this response only. return response["tool"] def list_tools(sender_id: str, enabled: bool = None) -> list: """List tools for an agent.""" params = {} if enabled is not None: params["enabled"] = "true" if enabled else "false" response = zavu_request("GET", f"/v1/senders/{sender_id}/agent/tools", params=params) return response["items"] def test_tool(sender_id: str, tool_id: str, test_params: dict) -> dict: """Run a tool with sample parameters. This calls the tool's real webhook.""" response = zavu_request( "POST", f"/v1/senders/{sender_id}/agent/tools/{tool_id}/test", json={"testParams": test_params}, ) return response["run"] # run["success"], run["statusCode"], run["response"]

    Example usage:

    Python
    from .services import create_tool # Create a tool to check order status tool = create_tool( sender_id="sender_abc123", name="get_order_status", description="Get the current status of a customer order", webhook_url="https://yourdomain.com/api/tools/order-status", webhook_secret="your_tool_webhook_secret", parameters={ "type": "object", "properties": { "order_id": { "type": "string", "description": "The order ID to look up" } }, "required": ["order_id"] } ) print(f"Tool created: {tool['id']}")

    Then create an endpoint to handle tool invocations:

    Python
    # agent/views.py @csrf_exempt @require_POST def tool_webhook(request, tool_id): """Handle tool calls from the AI agent.""" import os import json import hmac import hashlib # Zavu signs the raw body with the tool's secret: X-Zavu-Signature is its hex HMAC-SHA256. signature = request.headers.get('X-Zavu-Signature', '') secret = os.environ.get('ZAVU_TOOL_WEBHOOK_SECRET', '') expected = hmac.new(secret.encode('utf-8'), request.body, hashlib.sha256).hexdigest() if not secret or not hmac.compare_digest(expected, signature): return HttpResponse(status=401) try: payload = json.loads(request.body) # The body is {"tool": ..., "arguments": {...}, "context": {...}, "timestamp": ...} order_id = payload.get('arguments', {}).get('order_id') # Call your internal API/service order_status = get_order_from_database(order_id) return JsonResponse({ "success": True, "data": { "order_id": order_id, "status": order_status.status, "estimated_delivery": order_status.delivery_date, "tracking_url": order_status.tracking_url } }) except Exception as e: logger.error(f"Tool error: {e}") return JsonResponse({ "success": False, "error": str(e) }, status=500)

    Now when a customer asks "Where's my order ORD-12345?", the AI will automatically call your tool with the order ID and provide the response.

    Conversation Flows

    Build guided conversation paths for specific workflows through the dashboard flow builder.

    Analytics

    Track token usage, costs, and performance metrics directly in your Zavu dashboard under the Analytics section.

    Using Your Own AI Credentials (Optional)

    If you prefer to use your own AI provider credentials for billing purposes, set them on the agent itself:

  • When creating the agent, use provider: "openai" (or anthropic, google, mistral) instead of provider: "zavu"
  • Send your provider key as apiKey in the same request (POST /v1/senders/{senderId}/agent), or later with PATCH /v1/senders/{senderId}/agent
  • In the dashboard, the same fields are on the sender's AI Agent tab
  • This gives you full control over billing while still benefiting from Zavu's unified API and conversation management.

    Custom Webhook Logic (Advanced)

    If you need custom processing alongside the AI agent, you can add logic in your webhook:

    Python
    @csrf_exempt @require_POST def webhook(request): """Handle incoming WhatsApp messages from Zavu.""" signature = request.headers.get('X-Zavu-Signature', '') if not verify_webhook_signature(request.body, signature): return HttpResponse(status=401) try: payload = json.loads(request.body) except json.JSONDecodeError: return JsonResponse({"error": "Invalid JSON"}, status=400) if payload.get('type') == 'message.inbound': message = payload.get('data', {}) sender = message.get('from') text = message.get('text', '') logger.info(f"Message from {sender}: {text}") # Example: alert your team when someone asks for a person. # notify_support_team is your own code (Slack, email, a ticket). Zavu does not # hand the conversation over: the AI agent keeps answering it. if text.lower() == 'human': notify_support_team(sender, text) send_whatsapp_message( to=sender, text="Thanks. We have passed your message to our team." ) return JsonResponse({"status": "ok"})

    Next Steps

    • Explore the AI Agents dashboard to monitor conversations
    • Add knowledge bases for domain-specific responses
    • Create custom tools to integrate with your backend systems
    • Build conversation flows for specific use cases
    • Add support for media messages (images, documents)

    Check out the Zavu documentation for more examples and advanced features.

    Need help? Contact us or join our Discord community for support.

    Demo

    See it in action

    Book a personalized demo to see how Zavu AI Agents can transform your customer communication.

    Build a WhatsApp AI Agent with Django and Zavu | Zavu Blog