In this tutorial, you'll build a production-ready WhatsApp AI agent using NestJS 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 NestJS application that:
- Receives incoming WhatsApp messages via webhooks
- Verifies webhook signatures for security
- Uses Zavu's managed AI agents for intelligent responses
- Leverages NestJS's dependency injection and modular architecture
- Automatically maintains conversation context
Prerequisites
- Node.js 18+
- A Zavu account with API credentials
- Basic TypeScript 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 NestJS project and install dependencies:
Choose your package manager:
Bun (recommended):
terminalbun install @zavudev/sdk @nestjs/config dotenv
npm:
terminalnpm install @zavudev/sdk @nestjs/config dotenv
pnpm:
terminalpnpm add @zavudev/sdk @nestjs/config dotenv
Then create the project:
terminalnpx @nestjs/cli new whatsapp-agent cd whatsapp-agent
Project Structure
whatsapp-agent/
├── src/
│ ├── app.module.ts
│ ├── main.ts
│ ├── webhook/
│ │ ├── webhook.module.ts
│ │ ├── webhook.controller.ts
│ │ ├── webhook.service.ts
│ │ └── dto/
│ │ └── webhook-event.dto.ts
│ └── zavu/
│ ├── zavu.module.ts
│ └── zavu.service.ts
├── .env
└── nest-cli.jsonEnvironment Configuration
Create a .env file in your project root:
terminalZAVUDEV_API_KEY=your_zavu_api_key ZAVU_WEBHOOK_SECRET=your_webhook_secret PORT=3000
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.
Create the Zavu Module
Create src/zavu/zavu.module.ts:
TypeScriptimport { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import { ZavuService } from './zavu.service'; @Module({ imports: [ConfigModule], providers: [ZavuService], exports: [ZavuService], }) export class ZavuModule {}
Create src/zavu/zavu.service.ts:
TypeScriptimport { Injectable } from '@nestjs/common'; import { ConfigService } from '@nestjs/config'; import Zavudev from '@zavudev/sdk'; @Injectable() export class ZavuService { private readonly zavu: Zavudev; constructor(private configService: ConfigService) { this.zavu = new Zavudev({ apiKey: this.configService.get<string>('ZAVUDEV_API_KEY'), }); } getClient(): Zavudev { return this.zavu; } async createAgent(senderId: string, name: string, systemPrompt: string, model = 'gpt-4o-mini') { await this.zavu.senders.agent.create(senderId, { name, provider: 'zavu', model, systemPrompt, contextWindowMessages: 10, includeContactMetadata: true }); // Agents are created disabled. Switch it on once it is configured. const { agent } = await this.zavu.senders.agent.update(senderId, { enabled: true }); return agent; } async createKnowledgeBase(senderId: string, name: string, description?: string) { return await this.zavu.senders.agent.knowledgeBases.create(senderId, { name, description }); } async addDocumentToKB(senderId: string, kbId: string, title: string, content: string) { return await this.zavu.senders.agent.knowledgeBases.documents.create(kbId, { senderId, title, content }); } async createTool(senderId: string, name: string, description: string, webhookUrl: string, parameters: any) { return await this.zavu.senders.agent.tools.create(senderId, { name, description, webhookUrl, parameters }); } }
Create the Webhook Module
Create src/webhook/dto/webhook-event.dto.ts:
TypeScriptexport class WebhookEventDto { type: string; data: any; timestamp?: string; }
Create src/webhook/webhook.service.ts:
TypeScriptimport { Injectable, Logger } from '@nestjs/common'; import { ConfigService } from '@nestjs/config'; import as crypto from 'crypto'; @Injectable() export class WebhookService { private readonly logger = new Logger(WebhookService.name); constructor(private configService: ConfigService) {} // X-Zavu-Signature: t=<seconds>,v2=<hex> (v1=<hex> on older webhooks). // v2 signs "<t>.<body>"; v1 signs the body alone. verifyWebhookSignature(rawBody: Buffer | undefined, header: string): boolean { const secret = this.configService.get<string>('ZAVU_WEBHOOK_SECRET'); if (!rawBody || !header || !secret) return false; const parts: Record<string, string> = {}; for (const piece of header.split(',')) { const i = piece.indexOf('='); if (i > 0) parts[piece.slice(0, i)] = piece.slice(i + 1); } const timestamp = Number(parts.t); if (!Number.isFinite(timestamp)) return false; const age = Math.floor(Date.now() / 1000) - timestamp; if (age > 300 || age < -60) return false; const received = parts.v2 ?? parts.v1; if (!received) return false; const body = rawBody.toString('utf8'); const signedPayload = parts.v2 ?: body; const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex'); if (expected.length !== received.length) return false; return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); } async handleWebhookEvent(event: any) { this.logger.log(${timestamp}.${body}Received webhook event:${event.type}); if (event.type === 'message.inbound') { const message = event.data; this.logger.log(Message from${message.from}: ${message.text}); } return { status: 'ok' }; } }
Create src/webhook/webhook.controller.ts:
TypeScriptimport { Controller, Post, Body, Headers, Req, HttpStatus, HttpException, RawBodyRequest } from '@nestjs/common'; import { Request } from 'express'; import { WebhookService } from './webhook.service'; @Controller('webhook') export class WebhookController { constructor(private readonly webhookService: WebhookService) {} @Post() async handleWebhook( @Body() body: any, @Headers('x-zavu-signature') signature: string, @Req() req: RawBodyRequest<Request>, ) { if (!this.webhookService.verifyWebhookSignature(req.rawBody, signature)) { throw new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED); } try { return await this.webhookService.handleWebhookEvent(body); } catch (error) { throw new HttpException( 'Internal server error', HttpStatus.INTERNAL_SERVER_ERROR ); } } }
Create src/webhook/webhook.module.ts:
TypeScriptimport { Module } from '@nestjs/common'; import { WebhookController } from './webhook.controller'; import { WebhookService } from './webhook.service'; import { ZavuModule } from '../zavu/zavu.module'; @Module({ imports: [ZavuModule], controllers: [WebhookController], providers: [WebhookService], }) export class WebhookModule {}
Update the App Module
Update src/app.module.ts:
TypeScriptimport { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import { WebhookModule } from './webhook/webhook.module'; @Module({ imports: [ ConfigModule.forRoot({ isGlobal: true, }), WebhookModule, ], }) export class AppModule {}
Update main.ts
Update src/main.ts:
TypeScriptimport { NestFactory } from '@nestjs/core'; import { ValidationPipe } from '@nestjs/common'; import { AppModule } from './app.module'; async function bootstrap() { // rawBody: true keeps the exact bytes on req.rawBody for signature verification const app = await NestFactory.create(AppModule, { rawBody: true }); app.useGlobalPipes(new ValidationPipe()); const PORT = process.env.PORT || 3000; await app.listen(PORT); console.log(); } bootstrap();Application is running on: http://localhost:${PORT}
Deploy and Configure
terminalnpm run start:prod
Create a Managed AI Agent
Option 1: Via Zavu Dashboard
Create an agent directly in the Zavu Dashboard.
Option 2: Via NestJS Service
Create a controller src/agent/agent.controller.ts:
TypeScriptimport { Controller, Post, Body } from '@nestjs/common'; import { ZavuService } from '../zavu/zavu.service'; @Controller('agent') export class AgentController { constructor(private readonly zavuService: ZavuService) {} @Post('create') async createAgent(@Body() body: { senderId: string; name: string; systemPrompt: string; model?: string; }) { const agent = await this.zavuService.createAgent( body.senderId, body.name, body.systemPrompt, body.model ); return { agent }; } }
Knowledge Bases
TypeScript// In zavu.service.ts async createKnowledgeBase(senderId: string, name: string, description?: string) { const response = await this.zavu.senders.agent.knowledgeBases.create(senderId, { name, description }); return response.knowledgeBase; } async addDocumentToKB(senderId: string, kbId: string, title: string, content: string) { const response = await this.zavu.senders.agent.knowledgeBases.documents.create(kbId, { senderId, title, content }); return response.document; }
Custom Tools
TypeScript// In zavu.service.ts async createTool( senderId: string, name: string, description: string, webhookUrl: string, parameters: any ) { const response = await this.zavu.senders.agent.tools.create(senderId, { name, description, webhookUrl, parameters }); return response.tool; }
Create a tool endpoint controller:
TypeScriptimport { Controller, Post, Body, Headers, Req, HttpException, HttpStatus, RawBodyRequest } from '@nestjs/common'; import { Request } from 'express'; import as crypto from 'crypto'; @Controller('tools') export class ToolsController { @Post('order-status') async getOrderStatus( // The body is { tool, arguments, context, timestamp } @Body() body: { tool: string; arguments: { order_id: string }; context: Record<string, unknown> }, @Headers('x-zavu-signature') signature: string, @Req() req: RawBodyRequest<Request>, ) { // Tool calls are signed differently from message webhooks: // X-Zavu-Signature is the hex HMAC-SHA256 of the raw body, keyed with the tool's own secret. const secret = process.env.ZAVU_TOOL_WEBHOOK_SECRET; const expected = secret && req.rawBody ? crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex') : ''; if (!expected || !signature || expected.length !== signature.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { throw new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED); } const orderId = body.arguments.order_id; const orderStatus = await this.getOrderFromDatabase(orderId); return { success: true, data: { order_id: orderId, status: orderStatus.status, estimated_delivery: orderStatus.delivery_date, tracking_url: orderStatus.tracking_url } }; } private async getOrderFromDatabase(orderId: string) { return { status: 'shipped', delivery_date: '2024-01-20', tracking_url: 'https://tracker.example.com/ORD-12345' }; } }
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 you create it, pass provider: "openai" (or "anthropic", "google", "mistral") together with apiKey, your key for that provider, instead of provider: "zavu". You can also pick the provider and enter the key on the sender's Agent tab in the dashboard.
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
Check out the Zavu documentation for more examples and advanced features.