> 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.
Build a high-performance WhatsApp AI agent using FastAPI's async capabilities and Zavu's managed AI Gateway. The best part? You don't need to manage any external AI API keys - Zavu gives you access to all top-tier AI models (GPT-4, Claude, Gemini, Mistral, and more) directly from your dashboard.
What We're Building
A FastAPI application that:
- Receives incoming WhatsApp messages via async 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 FastAPI 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 project and install dependencies:
terminalmkdir whatsapp-agent && cd whatsapp-agent python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install fastapi uvicorn httpx python-dotenv
Project Structure
whatsapp-agent/
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── models.py
│ ├── services.py
│ └── webhook.py
├── .env
└── requirements.txtEnvironment Configuration
Create a .env file:
terminalZAVUDEV_API_KEY=your_zavu_api_key ZAVU_WEBHOOK_SECRET=your_webhook_secret
That's it! No OpenAI, Anthropic, or other AI provider keys needed.
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:
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 app/services.py, using httpx:
Pythonimport os import httpx ZAVU_API = "https://api.zavu.dev" async def zavu_request(method: str, path: str, kwargs) -> dict: """Call the Zavu REST API with your API key and return the JSON body.""" async with httpx.AsyncClient(base_url=ZAVU_API, timeout=30) as client: response = await client.request( method, path, headers={ "Authorization": f"Bearer {os.environ.get('ZAVUDEV_API_KEY')}", "Content-Type": "application/json", }, kwargs, ) response.raise_for_status() return response.json() if response.content else {} async 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.""" await 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 = await zavu_request("PATCH", f"/v1/senders/{sender_id}/agent", json={"enabled": True}) return response["agent"] async def get_agent_stats(sender_id: str) -> dict: """Get statistics for an AI agent.""" return await zavu_request("GET", f"/v1/senders/{sender_id}/agent/stats") async def list_agent_executions(sender_id: str, limit: int = 50) -> list: """List recent agent executions.""" response = await zavu_request( "GET", f"/v1/senders/{sender_id}/agent/executions", params={"limit": limit}, ) return response["items"]
Now you can create an agent from FastAPI code:
Python# Example: Create an agent from a startup event or API endpoint from .services import create_ai_agent agent = await 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:
| Provider | Models |
|---|---|
| OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo |
| Anthropic | claude-3-5-sonnet, claude-3-opus, claude-3-haiku |
| gemini-pro, gemini-1.5-pro | |
| Mistral | mistral-large, mistral-medium |
Simply change the model in your agent configuration through the dashboard or with PATCH /v1/senders/{senderId}/agent.
Define Pydantic Models
Create app/models.py:
Pythonfrom 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): messageId: 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"
Create the Services Layer
Create app/services.py:
Pythonimport os import hmac import hashlib import time import httpx ZAVU_API = "https://api.zavu.dev" MAX_AGE_SECONDS = 300 async def zavu_request(method: str, path: str, kwargs) -> dict: """Call the Zavu REST API with your API key and return the JSON body.""" async with httpx.AsyncClient(base_url=ZAVU_API, timeout=30) as client: response = await client.request( method, path, headers={ "Authorization": f"Bearer {os.environ.get('ZAVUDEV_API_KEY')}", "Content-Type": "application/json", }, kwargs, ) response.raise_for_status() return response.json() if response.content else {} def verify_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) async def send_whatsapp_message(to: str, text: str) -> dict: """Send a WhatsApp message with POST /v1/messages.""" response = await zavu_request( "POST", "/v1/messages", json={"to": to, "text": text, "channel": "whatsapp"}, ) return response["message"]
Create the Webhook Router
Create app/webhook.py:
Pythonimport 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") ): """Handle incoming WhatsApp messages from Zavu.""" body = await request.body() if not verify_signature(body, x_zavu_signature or ""): raise HTTPException(status_code=401, detail="Invalid signature") try: payload = WebhookPayload.model_validate_json(body) except Exception as e: logger.error(f"Invalid payload: {e}") raise HTTPException(status_code=400, detail="Invalid payload") if payload.type == "message.inbound": await process_inbound_message(payload) return {"status": "ok"} async def process_inbound_message(payload: WebhookPayload): """Process incoming message - AI agent handles response automatically.""" message = payload.data if message.messageType != "text": logger.info(f"Ignoring non-text message: {message.messageType}") return sender = message.from_ text = message.text if not sender or not text: return logger.info(f"Received from {sender}: {text}") # With a managed AI agent configured, Zavu automatically handles the AI response # The webhook is primarily for logging or custom business logic # 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) await send_whatsapp_message( to=sender, text="Thanks. We have passed your message to our team." )
Main Application
Create app/main.py:
Pythonimport 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("Starting WhatsApp AI Agent...") yield print("Shutting down...") app = FastAPI( title="WhatsApp AI Agent", description="AI-powered WhatsApp agent using Zavu", version="1.0.0", lifespan=lifespan ) app.include_router(webhook_router, prefix="/api") @app.get("/health") async def health_check(): return {"status": "healthy"}
With a managed AI agent configured, Zavu automatically handles the AI response. The webhook is primarily for logging or custom business logic.
Run the Application
terminaluvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
Configure Webhook
https://yourdomain.com/api/webhook - Enable: message.inbound - Copy the webhook secret to your .envLocal Development with ngrok
terminalngrok http 8000
Use the HTTPS URL from ngrok in your Zavu webhook settings.
API Documentation
FastAPI automatically generates OpenAPI docs at /docs:
terminalcurl http://localhost:8000/docs
Managed Agent Features
Zavu's AI agents come with powerful built-in features:
Knowledge Bases
Create RAG-powered responses by uploading documents to give your agent domain-specific knowledge.
#### Via Dashboard
#### Via the REST API
Pythonasync 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 = await zavu_request("POST", f"/v1/senders/{sender_id}/agent/knowledge-bases", json=body) return response["knowledgeBase"] async 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 = await zavu_request( "POST", f"/v1/senders/{sender_id}/agent/knowledge-bases/{kb_id}/documents", json={"title": title, "content": content}, ) return response["document"] # Example usage kb = await create_knowledge_base( sender_id="sender_abc123", name="Product FAQ", description="Frequently asked questions about our products" ) await 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." )
Custom Tools
Connect external APIs to extend your agent's capabilities by creating tools that the AI can call.
#### Via Dashboard
#### Via the REST API
Pythonasync 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 = await 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"] # Example: Create a tool to check order status tool = await 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"] } )
Then create an endpoint to handle tool invocations:
Python@router.post("/tools/order-status") async def handle_order_tool(request: Request): """Handle tool calls from the AI agent.""" import os import hmac import hashlib # Zavu signs the raw body with the tool's secret: X-Zavu-Signature is its hex HMAC-SHA256. body = await request.body() signature = request.headers.get("X-Zavu-Signature", "") secret = os.environ.get("ZAVU_TOOL_WEBHOOK_SECRET", "") expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest() if not secret or not hmac.compare_digest(expected, signature): raise HTTPException(status_code=401) payload = await request.json() # The body is {"tool": ..., "arguments": {...}, "context": {...}, "timestamp": ...} order_id = payload.get("arguments", {}).get("order_id") # Call your internal API/service order_status = await get_order_from_database(order_id) return { "success": True, "data": { "order_id": order_id, "status": order_status.status, "estimated_delivery": order_status.delivery_date } }
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:
provider: "openai" (or anthropic, google, mistral) instead of provider: "zavu"apiKey in the same request (POST /v1/senders/{senderId}/agent), or later with PATCH /v1/senders/{senderId}/agentThis 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@router.post("/webhook") async def handle_webhook( request: Request, x_zavu_signature: Optional[str] = Header(None, alias="X-Zavu-Signature") ): """Handle incoming WhatsApp messages from Zavu.""" body = await request.body() if not verify_signature(body, x_zavu_signature or ""): raise HTTPException(status_code=401, detail="Invalid signature") try: payload = WebhookPayload.model_validate_json(body) except Exception as e: logger.error(f"Invalid payload: {e}") raise HTTPException(status_code=400, detail="Invalid payload") if payload.type == "message.inbound": message = payload.data sender = message.from_ text = message.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 and text.lower() == 'human': notify_support_team(sender, text) await send_whatsapp_message( to=sender, text="Thanks. We have passed your message to our team." ) return {"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.