--- title: Build a WhatsApp AI Agent with NestJS and Zavu description: Learn how to build an AI-powered WhatsApp agent using NestJS and Zavu's managed AI Gateway. date: 2025-12-23 author: Jennifer Villalobos locale: en source: https://www.zavu.dev/en/blog/whatsapp-ai-agents-nestjs tags: AI Agents, WhatsApp, NestJS, TypeScript --- # Build a WhatsApp AI Agent with NestJS and Zavu 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)**: ```bash bun install @zavudev/sdk @nestjs/config dotenv ``` **npm**: ```bash npm install @zavudev/sdk @nestjs/config dotenv ``` **pnpm**: ```bash pnpm add @zavudev/sdk @nestjs/config dotenv ``` Then create the project: ```bash npx @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.json ``` ## Environment Configuration Create a `.env` file in your project root: ```bash ZAVUDEV_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`: ```typescript import { 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`: ```typescript import { 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('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`: ```typescript export class WebhookEventDto { type: string; data: any; timestamp?: string; } ``` Create `src/webhook/webhook.service.ts`: ```typescript import { 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=,v2= (v1= on older webhooks). // v2 signs "."; v1 signs the body alone. verifyWebhookSignature(rawBody: Buffer | undefined, header: string): boolean { const secret = this.configService.get('ZAVU_WEBHOOK_SECRET'); if (!rawBody || !header || !secret) return false; const parts: Record = {}; 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 ? `${timestamp}.${body}` : 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(`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`: ```typescript import { 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, ) { 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`: ```typescript import { 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`: ```typescript import { 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`: ```typescript import { 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(`Application is running on: http://localhost:${PORT}`); } bootstrap(); ``` ## Deploy and Configure 1. Deploy your NestJS app to a server with HTTPS 2. Configure the webhook in your Zavu dashboard 3. Create an AI agent for your sender 4. Run the server: ```bash npm 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`: ```typescript import { 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: ```typescript import { 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 }, @Headers('x-zavu-signature') signature: string, @Req() req: RawBodyRequest, ) { // 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](https://www.zavu.dev/docs) for more examples and advanced features.