AI AgentsWhatsAppNestJSTypeScript

Build a WhatsApp AI Agent with NestJS and Zavu

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

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

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):

terminal
bun install @zavudev/sdk @nestjs/config dotenv

npm:

terminal
npm install @zavudev/sdk @nestjs/config dotenv

pnpm:

terminal
pnpm add @zavudev/sdk @nestjs/config dotenv

Then create the project:

terminal
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:

terminal
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<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:

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=<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 ? ${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<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:

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

  • Deploy your NestJS app to a server with HTTPS
  • Configure the webhook in your Zavu dashboard
  • Create an AI agent for your sender
  • Run the server:
  • terminal
    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<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.

    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 NestJS and Zavu | Zavu Blog