En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando Fastify 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 Fastify 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 válidación de esquemas integrada de Fastify
- 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 JavaScript/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 e instala las dependencias:
Elige tu gestor de paquetes:
Bun (recomendado):
terminalbun install @zavudev/sdk fastify @fastify/env dotenv
npm:
terminalnpm install @zavudev/sdk fastify @fastify/env dotenv
pnpm:
terminalpnpm add @zavudev/sdk fastify @fastify/env dotenv
Luego crea el proyecto:
terminalmkdir whatsapp-agent && cd whatsapp-agent npm init -y
Estructura del Proyecto
whatsapp-agent/
├── src/
│ ├── app.js
│ ├── routes/
│ │ └── webhook.js
│ └── zavu.js
├── .env
└── package.jsonConfiguración del Entorno
Crea un archivo .env en la raiz de tu proyecto:
terminalZAVUDEV_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, y opcionalmente agregar tus propias API keys si prefieres usar tus propias credenciales para facturación.
Inicializar el Cliente de Zavu
Crea src/zavu.js:
JavaScriptimport Zavudev from '@zavudev/sdk'; export const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY, });
Crear la Aplicación Fastify
Crea src/app.js:
JavaScriptimport Fastify from 'fastify'; import dotenv from 'dotenv'; import { webhookRoutes } from './routes/webhook.js'; import { zavu } from './zavu.js'; dotenv.config(); const fastify = Fastify({ logger: true, }); // Registrar rutas fastify.register(webhookRoutes, { zavu }); // Health check fastify.get('/health', async () => { return { status: 'healthy' }; }); // Iniciar servidor const start = async () => { try { const PORT = process.env.PORT || 3000; await fastify.listen({ port: PORT, host: '0.0.0.0' }); console.log(); } catch (err) { fastify.log.error(err); process.exit(1); } }; start();Servidor corriendo en puerto${PORT}
Crear la Ruta del Webhook
Crea src/routes/webhook.js:
JavaScriptimport crypto from 'crypto'; export async function webhookRoutes(fastify, options) { const { zavu } = options; // Esquema para válidación de webhook const webhookSchema = { headers: { type: 'object', properties: { 'x-zavu-signature': { type: 'string' } }, required: ['x-zavu-signature'] }, body: { type: 'object', properties: { type: { type: 'string' }, data: { type: 'object' } }, required: ['type'] } }; // Guarda el body crudo: la firma cubre los bytes exactos que envio Zavu. fastify.addContentTypeParser('application/json', { parseAs: 'string' }, (request, body, done) => { request.rawBody = body; try { done(null, JSON.parse(body)); } catch (err) { done(err); } }); // X-Zavu-Signature: t=<segundos>,v2=<hex> (v1=<hex> en webhooks antiguos). // v2 firma "<t>.<body>"; v1 firma solo el body. function verifyWebhookSignature(rawBody, header) { const secret = process.env.ZAVU_WEBHOOK_SECRET; if (!header || !secret) return false; const parts = {}; 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)); } // Endpoint del webhook fastify.post('/webhook', { schema: webhookSchema }, async (request, reply) => { const signature = request.headers['x-zavu-signature']; const rawBody = request.rawBody; // Verificar firma del webhook if (!verifyWebhookSignature(rawBody, signature)) { fastify.log.warn('Firma de webhook inválida'); return reply.status(401).send({ error: 'No autorizado' }); } try { const payload = request.body; const eventType = payload.type; fastify.log.info(${timestamp}.${rawBody}Evento de webhook recibido:${eventType}); // Manejar diferentes tipos de eventos if (eventType === 'message.inbound') { const message = payload.data; fastify.log.info(Mensaje de${message.from}: ${message.text}); } return { status: 'ok' }; } catch (error) { fastify.log.error('Error de webhook:', error); return reply.status(500).send({ error: 'Error interno del servidor' }); } }); }
Actualizar package.json
Agrega un script de inicio a package.json:
JSON{ "type": "module", "scripts": { "start": "node src/app.js", "dev": "node --watch src/app.js" } }
Desplegar y Configurar
https://tudominio.com/webhook - Habilita eventos: message.inbound - Copia el secreto del webhook a tu archivo .envterminalnpm start
Pruebas Locales con ngrok
Para desarrollo local, usa ngrok para exponer tu servidor:
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 SDK de JavaScript
JavaScriptimport { zavu } from './zavu.js'; async function createAIAgent(senderId, name, systemPrompt, model = 'gpt-4o-mini') { await zavu.senders.agent.create(senderId, { name: name, provider: 'zavu', model: model, systemPrompt: systemPrompt, contextWindowMessages: 10, includeContactMetadata: true }); // Los agentes se crean deshabilitados. Activalo cuando este configurado. const response = await zavu.senders.agent.update(senderId, { enabled: true }); return response.agent; } // Uso const agent = await createAIAgent( 'sender_abc123', 'Bot de Soporte al Cliente',);Eres un asistente de soporte al cliente amigable para Zavu. Reglas: - Se amable y conciso - Ayuda con preguntas sobre mensajería WhatsApp, SMS y email - Si no estas seguro, dilo e indica al cliente que escriba a soporte@tuempresa.com - Responde en el mismo idioma que el cliente); console.log(Agente creado:${agent.id}
Bases de Conocimiento
Crea respuestas potenciadas por RAG subiendo documentos.
JavaScriptimport { zavu } from './zavu.js'; // Crear base de conocimiento const { knowledgeBase: kb } = await zavu.senders.agent.knowledgeBases.create('sender_abc123', { name: 'FAQ de Productos', description: 'Preguntas frecuentes sobre nuestros productos' }); // Agregar documentos await zavu.senders.agent.knowledgeBases.documents.create(kb.id, { senderId: 'sender_abc123', title: 'Política de Devoluciónes', content:);Nuestra política de devoluciónes permite devoluciónes dentro de 30 dias de la compra. Los artículos deben estar: - En condicion original - Con recibo o comprobante de compra - Sin uso o daños}); console.log(Base de conocimiento creada:${kb.id}
Herramientas Personalizadas
Conecta APIs externas para extender las capacidades de tu agente.
JavaScriptimport { zavu } from './zavu.js'; // Crear una herramienta const { tool } = await zavu.senders.agent.tools.create('sender_abc123', { name: 'get_order_status', description: 'Obtener el estado actual de un pedido de cliente', webhookUrl: 'https://tudominio.com/api/tools/order-status', webhookSecret: process.env.ZAVU_TOOL_WEBHOOK_SECRET, // firma cada llamada a esta herramienta parameters: { type: 'object', properties: { order_id: { type: 'string', description: 'El ID del pedido a buscar' } }, required: ['order_id'] } }); console.log();Herramienta creada:${tool.id}
Luego crea el endpoint de la herramienta con Fastify:
JavaScript// En tu archivo de rutas fastify.post('/api/tools/order-status', async (request, reply) => { // 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 signature = request.headers['x-zavu-signature'] || ''; const secret = process.env.ZAVU_TOOL_WEBHOOK_SECRET; const expected = secret ? crypto.createHmac('sha256', secret).update(request.rawBody).digest('hex') : ''; if (!expected || expected.length !== signature.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { return reply.status(401).send({ error: 'Unauthorized' }); } // El body es { tool, arguments, context, timestamp } const order_id = request.body.arguments?.order_id; // Llamar a tu API/servicio interno const orderStatus = await getOrderFromDatabase(order_id); return { success: true, data: { order_id: order_id, status: orderStatus.status, estimated_delivery: orderStatus.delivery_date, tracking_url: orderStatus.tracking_url } }; });
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
- Construye flujos de conversación para casos de uso específicos
Consulta la documentación de Zavu para más ejemplos y funciones avanzadas.