Agentes IAWhatsAppNestJSTypeScript

Construye un Agente de IA para WhatsApp con NestJS y Zavu

Aprende a construir un agente de WhatsApp potenciado por IA usando NestJS y el AI Gateway administrado de Zavu.

Redactado por: Jennifer VillalobosRevisado por: Victor Villalobos23 de diciembre de 202512 min
Ver como Markdown

En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando NestJS y Zavu. La mejor parte? No necesitas gestiónar ninguna API key de IA externa - el AI Gateway de Zavu te da acceso a todos los modelos de IA de primer nivel (GPT-4, Claude, Gemini, Mistral y más) directamente desde tu dashboard de Zavu.

Lo Que Construiremos

Una aplicación NestJS que:

  • Recibe mensajes entrantes de WhatsApp via webhooks
  • Verifica firmas de webhook para seguridad
  • Usa los agentes de IA administrados de Zavu para respuestas inteligentes
  • Aprovecha la inyeccion de dependencias y arquitectura modular de NestJS
  • Mantiene automáticamente el contexto de la conversacion

Requisitos Previos

  • Node.js 18+
  • Una cuenta de Zavu con credenciales de API
  • Conocimiento básico de TypeScript

No se requieren API keys de IA externas! El AI Gateway de Zavu proporciona acceso a todos los modelos de IA principales a través de una sola integración.

Instalacion

Crea un nuevo proyecto NestJS e instala las dependencias:

Elige tu gestor de paquetes:

Bun (recomendado):

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

Luego crea el proyecto:

terminal
npx @nestjs/cli new whatsapp-agent cd whatsapp-agent

Estructura del Proyecto

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

Configuración del Entorno

Crea un archivo .env en la raiz de tu proyecto:

terminal
ZAVUDEV_API_KEY=tu_api_key_de_zavu ZAVU_WEBHOOK_SECRET=tu_secreto_de_webhook PORT=3000

Eso es todo! No necesitas keys de OpenAI, Anthropic u otros proveedores de IA.

Como Funciona el AI Gateway de Zavu

Zavu proporciona un AI Gateway unificado que te da acceso a todos los modelos de IA de primer nivel sin gestiónar API keys individuales:

  • GPT-4o, GPT-4o-mini - Los modelos más recientes de OpenAI
  • Claude 3.5 Sonnet, Claude 3 Opus - Modelos de Anthropic
  • Gemini Pro - Modelos de IA de Google
  • Mistral Large - Modelos de Mistral AI

Puedes configurar que modelo usar directamente en tu dashboard de Zavu.

Crear el Modulo de Zavu

Crea 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 {}

Crea 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 }); // Los agentes se crean deshabilitados. Activalo cuando este configurado. 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 }); } }

Crear el Modulo de Webhook

Crea src/webhook/dto/webhook-event.dto.ts:

TypeScript
export class WebhookEventDto { type: string; data: any; timestamp?: string; }

Crea 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=<segundos>,v2=<hex> (v1=<hex> en webhooks antiguos). // v2 firma "<t>.<body>"; v1 firma solo el body. 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(Evento de webhook recibido: ${event.type}); if (event.type === 'message.inbound') { const message = event.data; this.logger.log(Mensaje de ${message.from}: ${message.text}); } return { status: 'ok' }; } }

Crea 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('No autorizado', HttpStatus.UNAUTHORIZED); } try { return await this.webhookService.handleWebhookEvent(body); } catch (error) { throw new HttpException( 'Error interno del servidor', HttpStatus.INTERNAL_SERVER_ERROR ); } } }

Crea 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 {}

Actualizar el Modulo de la Aplicación

Actualiza 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 {}

Actualizar main.ts

Actualiza src/main.ts:

TypeScript
import { NestFactory } from '@nestjs/core'; import { ValidationPipe } from '@nestjs/common'; import { AppModule } from './app.module'; async function bootstrap() { // rawBody: true guarda los bytes exactos en req.rawBody para verificar la firma const app = await NestFactory.create(AppModule, { rawBody: true }); app.useGlobalPipes(new ValidationPipe()); const PORT = process.env.PORT || 3000; await app.listen(PORT); console.log(Aplicación corriendo en: http://localhost:${PORT}); } bootstrap();

Desplegar y Configurar

  • Despliega tu app NestJS a un servidor con HTTPS
  • Configura el webhook en tu dashboard de Zavu
  • Crea un agente de IA para tu sender
  • Ejecuta el servidor:
  • terminal
    npm run start:prod

    Crear un Agente de IA Administrado

    Opcion 1: Via Dashboard de Zavu

    Crea un agente directamente en el Dashboard de Zavu.

    Opcion 2: Via Servicio NestJS

    Crea un controlador 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 }; } }

    Bases de Conocimiento

    TypeScript
    // En 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; }

    Herramientas Personalizadas

    TypeScript
    // En 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; }

    Crea un controlador para el endpoint de la herramienta:

    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( // El body es { 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>, ) { // Las llamadas a herramientas se firman distinto que los webhooks de mensajes: // X-Zavu-Signature es el HMAC-SHA256 en hex del body crudo, con el secreto propio de la herramienta. 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: 'enviado', delivery_date: '2024-01-20', tracking_url: 'https://tracker.example.com/ORD-12345' }; } }

    Usando Tus Propias Credenciales de IA (Opcional)

    Si prefieres usar tus propias credenciales de proveedor de IA para facturación, configuralas en el propio agente: al crearlo, pasa provider: "openai" (o "anthropic", "google", "mistral") junto con apiKey, tu key de ese proveedor, en lugar de provider: "zavu". Tambien puedes elegir el proveedor e ingresar la key en la pestana Agent del sender en el dashboard.

    Proximos Pasos

    • Explora el dashboard de AI Agents para monitorear conversaciones
    • Agrega bases de conocimiento para respuestas específicas del dominio
    • Crea herramientas personalizadas para integrar con tus sistemas backend

    Consulta la documentación de Zavu para más ejemplos y funciones avanzadas.

    Necesitas ayuda? Contáctanos o únete a nuestra comunidad en Discord para soporte.

    Demo

    Mira cómo funciona

    Agenda una demo personalizada para ver cómo los Agentes IA de Zavu pueden transformar tu comunicación con clientes.

    Construye un Agente de IA para WhatsApp con | Zavu Blog