--- title: Construye un Agente de IA para WhatsApp con Express y Zavu description: Aprende a construir un agente de WhatsApp potenciado por IA usando Express.js y el AI Gateway administrado de Zavu. date: 2025-12-23 author: Jennifer Villalobos locale: es source: https://www.zavu.dev/es/blog/whatsapp-ai-agents-express tags: Agentes IA, WhatsApp, Express, Node.js --- # Construye un Agente de IA para WhatsApp con Express y Zavu En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando Express.js 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 Express 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 - 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)**: ```bash bun install @zavudev/sdk express dotenv ``` **npm**: ```bash npm install @zavudev/sdk express dotenv ``` **pnpm**: ```bash pnpm add @zavudev/sdk express dotenv ``` Luego crea el proyecto: ```bash mkdir whatsapp-agent && cd whatsapp-agent npm init -y ``` ## Estructura del Proyecto ``` whatsapp-agent/ ├── src/ │ ├── app.js │ ├── webhook.js │ └── zavu.js ├── .env └── package.json ``` ## Configuración del Entorno Crea un archivo `.env` en la raiz de tu proyecto: ```bash 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, 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`: ```javascript import Zavudev from '@zavudev/sdk'; export const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY, }); ``` ## Crear un Agente de IA Administrado La forma más fácil de agregar capacidades de IA es a través de los agentes administrados de Zavu. Tienes dos opciones: ### Opcion 1: Via Dashboard de Zavu Crea un agente para tu sender directamente en el **Dashboard de Zavu**: 1. Ve a **Senders** en tu dashboard de Zavu 2. Seleccióna el sender al que quieres agregar capacidades de IA 3. Haz clic en la pestana **AI Agent** 4. Configura tu agente: - **Name**: Dale a tu agente un nombre descriptivo (ej. "Soporte al Cliente") - **Provider**: Seleccióna "Zavu" para usar el AI Gateway de Zavu (sin keys externas) - **Model**: Elige entre los modelos disponibles (gpt-4o-mini, claude-3-5-sonnet, etc.) - **System Prompt**: Define la personalidad e instrucciónes de tu agente - **Context Window**: Establece cuantos mensajes previos incluir como contexto 5. Habilita el agente y guarda Con el proveedor `zavu`, todo el procesamiento de IA es manejado por el gateway administrado de Zavu. Tu agente respondera automáticamente a los mensajes entrantes de WhatsApp sin código adicional! ### Opcion 2: Via SDK de JavaScript También puedes crear y configurar agentes de IA programaticamente usando el paquete `@zavudev/sdk`. ```javascript // src/agent.js import { zavu } from './zavu.js'; export async function createAIAgent(senderId, name, systemPrompt, model = 'gpt-4o-mini') { await zavu.senders.agent.create(senderId, { name: name, provider: 'zavu', // Usa el AI Gateway de Zavu (sin API keys externas) model: model, systemPrompt: systemPrompt, contextWindowMessages: 10, // Incluir últimos 10 mensajes como contexto includeContactMetadata: true, // Incluir info del contacto en contexto }); // Los agentes se crean deshabilitados. Activalo cuando este configurado. const response = await zavu.senders.agent.update(senderId, { enabled: true }); return response.agent; } ``` Ahora puedes crear un agente desde tu código Express: ```javascript import { createAIAgent } from './agent.js'; 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}`); ``` **Nota:** Al usar `provider: "zavu"`, el AI Gateway de Zavu maneja todo el acceso a modelos de IA. No se necesitan API keys externas! ## Modelos de IA Disponibles Al crear un agente, puedes elegir entre estos modelos: | Proveedor | Modelos | |----------|--------| | OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo | | Anthropic | claude-3-5-sonnet, claude-3-opus, claude-3-haiku | | Google | gemini-pro, gemini-1.5-pro | | Mistral | mistral-large, mistral-medium | Simplemente cambia el modelo en la configuración de tu agente a través del dashboard. ## Verificación de Firma de Webhook Crea `src/verify.js`: ```javascript import crypto from 'crypto'; export function verifyWebhookSignature(rawBody, header) { const secret = process.env.ZAVU_WEBHOOK_SECRET; if (!header || !secret) return false; // X-Zavu-Signature: t=,v2= (v1= en webhooks antiguos). // v2 firma "."; v1 firma solo el body. 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 ? `${timestamp}.${rawBody}` : 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)); } ``` ## Crear la Ruta del Webhook Crea `src/webhook.js`: ```javascript import { verifyWebhookSignature } from './verify.js'; export async function handleWebhook(req, res) { // req.body es el Buffer crudo (express.raw en esta ruta) const rawBody = req.body.toString('utf8'); const signature = req.headers['x-zavu-signature']; // Verificar firma del webhook if (!verifyWebhookSignature(rawBody, signature)) { console.warn('Firma de webhook inválida'); return res.status(401).json({ error: 'No autorizado' }); } try { const payload = JSON.parse(rawBody); const eventType = payload.type; console.log(`Evento de webhook recibido: ${eventType}`); // Manejar diferentes tipos de eventos if (eventType === 'message.inbound') { const message = payload.data; console.log(`Mensaje de ${message.from}: ${message.text}`); } return res.json({ status: 'ok' }); } catch (error) { console.error('Error de webhook:', error); return res.status(500).json({ error: 'Error interno del servidor' }); } } ``` ## Crear la Aplicación Express Crea `src/app.js`: ```javascript import express from 'express'; import dotenv from 'dotenv'; import { handleWebhook } from './webhook.js'; dotenv.config(); const app = express(); const PORT = process.env.PORT || 3000; // Body crudo para verificar la firma, antes de que corra express.json() app.use(['/webhook', '/api/tools'], express.raw({ type: 'application/json' })); // Parsear JSON para otras rutas app.use(express.json()); // Endpoint del webhook app.post('/webhook', handleWebhook); // Health check app.get('/health', (req, res) => { res.json({ status: 'healthy' }); }); app.listen(PORT, () => { console.log(`Servidor corriendo en puerto ${PORT}`); }); ``` ## 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 1. Despliega tu app Express a un servidor con HTTPS (requerido para webhooks) 2. Configura el webhook en tu dashboard de Zavu: - Ve a **Senders** > Seleccióna tu sender > **Webhook** - Establece URL a: `https://tudominio.com/webhook` - Habilita eventos: `message.inbound` - Copia el secreto del webhook a tu archivo `.env` 3. Crea un agente de IA para tu sender en el dashboard de Zavu o via API 4. Ejecuta el servidor: ```bash npm start ``` ## Pruebas Locales con ngrok Para desarrollo local, usa ngrok para exponer tu servidor: ```bash npx ngrok http 3000 ``` Copia la URL HTTPS y configurala en tu configuración de webhook de Zavu. ## Funciones del Agente Administrado Los agentes de IA de Zavu vienen con potentes funciones integradas, todas configurables a través del dashboard: ### Bases de Conocimiento Crea respuestas potenciadas por RAG subiendo documentos para dar a tu agente conocimiento específico del dominio. #### Via Dashboard 1. Ve a **Senders** > Seleccióna tu sender > **AI Agent** > **Knowledge Bases** 2. Haz clic en **Create Knowledge Base** 3. Sube documentos (PDF, TXT, MD) o pega contenido directamente 4. El agente usara automáticamente este conocimiento para responder preguntas #### Via SDK de JavaScript ```javascript import { zavu } from './zavu.js'; // Crear una base de conocimiento async function createKnowledgeBase(senderId, name, description) { const response = await zavu.senders.agent.knowledgeBases.create(senderId, { name: name, description: description }); return response.knowledgeBase; } // Agregar un documento a una base de conocimiento async function addDocumentToKB(senderId, kbId, title, content) { const response = await zavu.senders.agent.knowledgeBases.documents.create(kbId, { senderId: senderId, title: title, content: content }); return response.document; } ``` Ejemplo de uso: ```javascript // Crear una base de conocimiento const kb = await createKnowledgeBase( 'sender_abc123', 'FAQ de Productos', 'Preguntas frecuentes sobre nuestros productos' ); // Agregar documentos a la base de conocimiento await addDocumentToKB( 'sender_abc123', kb.id, 'Política de Devoluciónes', `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` ); ``` ### Herramientas Personalizadas Conecta APIs externas para extender las capacidades de tu agente creando herramientas que la IA puede llamar. #### Via Dashboard 1. Ve a **Senders** > Seleccióna tu sender > **AI Agent** > **Tools** 2. Haz clic en **Create Tool** 3. Configura la herramienta: - **Name**: Un nombre descriptivo (ej. "get_order_status") - **Description**: Lo que hace la herramienta (ayuda a la IA a decidir cuando usarla) - **Webhook URL**: Tu endpoint HTTPS que maneja la llamada de la herramienta - **Parameters**: JSON Schema definiendo los parametros esperados #### Via SDK de JavaScript ```javascript import { zavu } from './zavu.js'; // Crear una herramienta async function createTool(senderId, name, description, webhookUrl, parameters) { const response = await zavu.senders.agent.tools.create(senderId, { name: name, description: description, webhookUrl: webhookUrl, parameters: parameters }); return response.tool; } ``` Ejemplo de uso: ```javascript // Crear una herramienta para verificar estado de pedido const tool = await createTool( 'sender_abc123', 'get_order_status', 'Obtener el estado actual de un pedido de cliente', 'https://tudominio.com/api/tools/order-status', { type: 'object', properties: { order_id: { type: 'string', description: 'El ID del pedido a buscar' } }, required: ['order_id'] } ); console.log(`Herramienta creada: ${tool.id}`); // El secreto de firma solo se devuelve al crear. Guardalo como ZAVU_TOOL_WEBHOOK_SECRET. console.log(`Secreto del webhook: ${tool.webhookSecret}`); ``` Luego crea un endpoint para manejar invocaciones de herramientas: ```javascript import crypto from 'crypto'; // Endpoint de webhook de herramienta app.post('/api/tools/order-status', express.raw({ type: 'application/json' }), async (req, res) => { // 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 = req.headers['x-zavu-signature'] || ''; const secret = process.env.ZAVU_TOOL_WEBHOOK_SECRET; const expected = secret ? crypto.createHmac('sha256', secret).update(req.body).digest('hex') : ''; if (!expected || expected.length !== signature.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { return res.status(401).json({ error: 'Unauthorized' }); } try { // El body es { tool, arguments, context, timestamp } const payload = JSON.parse(req.body.toString('utf8')); const order_id = payload.arguments?.order_id; // Llamar a tu API/servicio interno const orderStatus = await getOrderFromDatabase(order_id); return res.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 res.status(500).json({ success: false, error: error.message }); } }); ``` Ahora cuando un cliente pregunte "Donde esta mi pedido ORD-12345?", la IA llamara automáticamente a tu herramienta con el ID del pedido y proporcionara la respuesta. ### Analíticas Rastrea uso de tokens, costos y latencia en la pestana **Agent** del sender en el dashboard, o leelos con `zavu.senders.agent.stats(senderId)` y `zavu.senders.agent.executions.list(senderId)`. ## 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. Esto te da control total sobre la facturación mientras sigues beneficiandote de la API unificada y gestión de conversaciones de Zavu. ## Lógica de Webhook Personalizada (Avanzado) Si necesitas procesamiento personalizado junto al agente de IA, puedes agregar lógica en tu webhook: ```javascript export async function handleWebhook(req, res) { // req.body es el Buffer crudo (express.raw en esta ruta) const rawBody = req.body.toString('utf8'); const signature = req.headers['x-zavu-signature']; if (!verifyWebhookSignature(rawBody, signature)) { return res.status(401).json({ error: 'No autorizado' }); } try { const payload = JSON.parse(rawBody); if (payload.type === 'message.inbound') { const message = payload.data; const { from, text } = message; console.log(`Mensaje de ${from}: ${text}`); // Lógica personalizada: avisa a tu equipo (Slack, email, tu helpdesk). // Zavu no tiene traspaso a humano integrado, y el agente de IA sigue respondiendo aqui. if (text.toLowerCase() === 'human') { await notifyYourTeam({ from, text }); // tu propia funcion await zavu.messages.send({ to: from, text: 'Gracias. Le pasamos tu mensaje a nuestro equipo.' }); } } return res.json({ status: 'ok' }); } catch (error) { console.error('Error de webhook:', error); return res.status(500).json({ error: 'Error interno del servidor' }); } } ``` ## 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 soporte para mensajes multimedia (imágenes, documentos) Consulta la [documentación de Zavu](https://www.zavu.dev/docs) para más ejemplos y funciones avanzadas.