En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando Next.js App Router 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 Next.js que:
- Recibe mensajes entrantes de WhatsApp via Route Handlers
- Verifica firmas de webhook para seguridad
- Usa los agentes de IA administrados de Zavu para respuestas inteligentes
- Aprovecha Next.js App Router y Server Actions
- 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 React y 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 Next.js o agregalo a uno existente:
Elige tu gestor de paquetes:
Bun (recomendado):
terminalbun install @zavudev/sdk
npm:
terminalnpm install @zavudev/sdk
pnpm:
terminalpnpm add @zavudev/sdk
Luego crea el proyecto:
terminalnpx create-next-app@latest whatsapp-agent cd whatsapp-agent
Cuando se te pregunte, seleccióna:
- TypeScript: Si
- ESLint: Si
- App Router: Si
- Src directory: Si
- Import alias: @/*
Estructura del Proyecto
whatsapp-agent/
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ └── webhook/
│ │ │ └── route.ts
│ │ └── page.tsx
│ └── lib/
│ └── zavu.ts
├── .env.local
└── package.jsonConfiguración del Entorno
Crea un archivo .env.local en la raiz de tu proyecto:
terminalZAVUDEV_API_KEY=tu_api_key_de_zavu ZAVU_WEBHOOK_SECRET=tu_secreto_de_webhook
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.
Inicializar el Cliente de Zavu
Crea src/lib/zavu.ts:
TypeScriptimport Zavudev from '@zavudev/sdk'; export const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY, });
Crear el Route Handler del Webhook
Crea src/app/api/webhook/route.ts:
TypeScriptimport { NextRequest, NextResponse } from 'next/server'; import crypto from 'crypto'; import { zavu } from '@/lib/zavu'; // X-Zavu-Signature: t=<segundos>,v2=<hex> (v1=<hex> en webhooks antiguos). // v2 firma "<t>.<body>"; v1 firma solo el body. function verifyWebhookSignature(rawBody: string, header: string): boolean { const secret = process.env.ZAVU_WEBHOOK_SECRET; if (!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 signedPayload = parts.v2 ?: rawBody; 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)); } export async function POST(request: NextRequest) { try { const rawBody = await request.text(); const signature = request.headers.get('x-zavu-signature') || ''; if (!verifyWebhookSignature(rawBody, signature)) { console.error('Firma de webhook inválida'); return NextResponse.json({ error: 'No autorizado' }, { status: 401 }); } const payload = JSON.parse(rawBody); const eventType = payload.type; console.log(${timestamp}.${rawBody}Evento de webhook recibido:${eventType}); if (eventType === 'message.inbound') { const message = payload.data; console.log(Mensaje de${message.from}: ${message.text}); } return NextResponse.json({ status: 'ok' }); } catch (error) { console.error('Error de webhook:', error); return NextResponse.json( { error: 'Error interno del servidor' }, { status: 500 } ); } }
Desplegar y Configurar
https://tudominio.com/api/webhook - Habilita eventos: message.inbound - Copia el secreto del webhook a tu archivo .env.localterminalnpm run build npm start
Pruebas Locales
Para pruebas locales, usa ngrok:
terminalnpx ngrok http 3000
Copia la URL HTTPS y configurala en tu configuración de webhook de Zavu.
Crear un Agente de IA Administrado
Opcion 1: Via Dashboard de Zavu
Opcion 2: Via Server Actions
Crea una server action en src/app/actions/agent.ts:
TypeScript'use server'; import { zavu } from '@/lib/zavu'; import { revalidatePath } from 'next/cache'; export async function createAgent(formData: FormData) { const senderId = formData.get('senderId') as string; const name = formData.get('name') as string; const systemPrompt = formData.get('systemPrompt') as string; await zavu.senders.agent.create(senderId, { name, provider: 'zavu', model: 'gpt-4o-mini', systemPrompt, contextWindowMessages: 10, includeContactMetadata: true }); // Los agentes se crean deshabilitados. Activalo cuando este configurado. const response = await zavu.senders.agent.update(senderId, { enabled: true }); revalidatePath('/dashboard'); return response.agent; } export async function getAgentStats(senderId: string) { const response = await zavu.senders.agent.stats(senderId); return response; }
Bases de Conocimiento
Crea una server action para bases de conocimiento en src/app/actions/knowledge-base.ts:
TypeScript'use server'; import { zavu } from '@/lib/zavu'; export async function createKnowledgeBase(formData: FormData) { const senderId = formData.get('senderId') as string; const name = formData.get('name') as string; const description = formData.get('description') as string; const response = await zavu.senders.agent.knowledgeBases.create(senderId, { name, description }); return response.knowledgeBase; } export async function addDocument(formData: FormData) { const senderId = formData.get('senderId') as string; const kbId = formData.get('kbId') as string; const title = formData.get('title') as string; const content = formData.get('content') as string; const response = await zavu.senders.agent.knowledgeBases.documents.create(kbId, { senderId, title, content }); return response.document; }
Herramientas Personalizadas
Crea un endpoint de herramienta en src/app/api/tools/order-status/route.ts:
TypeScriptimport { NextRequest, NextResponse } from 'next/server'; import crypto from 'crypto'; // 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. function verifyToolSignature(rawBody: string, signature: string): boolean { const secret = process.env.ZAVU_TOOL_WEBHOOK_SECRET; if (!signature || !secret) return false; const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); if (expected.length !== signature.length) return false; return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } export async function POST(request: NextRequest) { try { const rawBody = await request.text(); if (!verifyToolSignature(rawBody, request.headers.get('x-zavu-signature') || '')) { return NextResponse.json({ error: 'No autorizado' }, { status: 401 }); } // El body es { tool, arguments, context, timestamp } const body = JSON.parse(rawBody); const order_id = body.arguments?.order_id; const orderStatus = await getOrderFromDatabase(order_id); return NextResponse.json({ success: true, data: { order_id: order_id, status: orderStatus.status, estimated_delivery: orderStatus.delivery_date, tracking_url: orderStatus.tracking_url } }); } catch (error) { console.error('Error de herramienta:', error); return NextResponse.json( { success: false, error: 'Error interno del servidor' }, { status: 500 } ); } } async function getOrderFromDatabase(orderId: string) { return { status: 'enviado', delivery_date: '2024-01-20', tracking_url: 'https://tracker.example.com/ORD-12345' }; }
Crea la herramienta via server action:
TypeScript// src/app/actions/tools.ts 'use server'; import { zavu } from '@/lib/zavu'; export async function createOrderStatusTool(formData: FormData) { const senderId = formData.get('senderId') as string; const webhookUrl =; const response = await zavu.senders.agent.tools.create(senderId, { name: 'get_order_status', description: 'Obtener el estado actual de un pedido de cliente', webhookUrl, parameters: { type: 'object', properties: { order_id: { type: 'string', description: 'El ID del pedido a buscar' } }, required: ['order_id'] } }); // El secreto de firma solo se devuelve al crear. Guardalo como ZAVU_TOOL_WEBHOOK_SECRET. console.log('Secreto del webhook de la herramienta:', response.tool.webhookSecret); return response.tool; }https://${process.env.VERCEL_URL || 'localhost:3000'}/api/tools/order-status
Usando Tus Propias Credenciales de IA (Opcional)
Si prefieres usar tus propias credenciales de proveedor de IA, 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.
Esto te da control total sobre la facturación mientras sigues beneficiandote de la API unificada de Zavu.
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
- Construye flujos de conversación para casos de uso específicos
- Agrega una UI de dashboard para administrar tus agentes
Consulta la documentación de Zavu para más ejemplos y funciones avanzadas.