Volver al Blog
Agentes IAWhatsAppExpressNode.js

Construye un Agente de IA para WhatsApp con Express y Zavu

Aprende a construir un agente de WhatsApp potenciado por IA usando Express.js y el AI Gateway administrado de Zavu. Sin necesidad de API keys externas - accede a GPT-4, Claude y mas a traves de Zavu.

Redactado por: Jennifer VillalobosRevisado por: Victor Villalobos23 de diciembre de 202510 min

Construye un Agente de IA para WhatsApp con Express y Zavu

En este tutorial, construiras un agente de IA para WhatsApp listo para produccion usando Express.js y Zavu. La mejor parte? No necesitas gestionar 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 mas) directamente desde tu dashboard de Zavu.

Lo Que Construiremos

Una aplicacion 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 automaticamente el contexto de la conversacion

Requisitos Previos

  • Node.js 18+
  • Una cuenta de Zavu con credenciales de API
  • Conocimiento basico 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 traves de una sola integracion.

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

text
whatsapp-agent/
├── src/
│   ├── app.js
│   ├── webhook.js
│   └── zavu.js
├── .env
└── package.json

Configuracion 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 gestionar API keys individuales:

  • GPT-4o, GPT-4o-mini - Los modelos mas 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 facturacion.

Inicializar el Cliente de Zavu

Crea src/zavu.js:

javascript
import Zavudev from '@zavudev/sdk';

export const zavu = new Zavu({
  apiKey: process.env.ZAVUDEV_API_KEY,
});

Crear un Agente de IA Administrado

La forma mas facil de agregar capacidades de IA es a traves 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:

  • Ve a Senders en tu dashboard de Zavu
  • Selecciona el sender al que quieres agregar capacidades de IA
  • Haz clic en la pestana AI Agent
  • Configura tu agente:
    • - Name: Dale a tu agente un nombre descriptivo (ej. "Soporte al Cliente") - Provider: Selecciona "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 instrucciones de tu agente - Context Window: Establece cuantos mensajes previos incluir como contexto
  • 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 automaticamente a los mensajes entrantes de WhatsApp sin codigo adicional!

    Opcion 2: Via SDK de JavaScript

    Tambien puedes crear y configurar agentes de IA programaticamente usando el paquete @zavudev/sdk.

    javascript
    import { zavu } from './zavu.js';

async function createAIAgent(senderId, name, systemPrompt, model = 'gpt-4o-mini') {
  const response = await zavu.senders.agent.create({
    senderId: senderId,
    name: name,
    provider: 'zavu', // Usa el AI Gateway de Zavu (sin API keys externas)
    model: model,
    systemPrompt: systemPrompt,
    contextWindowMessages: 10, // Incluir ultimos 10 mensajes como contexto
    includeContactMetadata: true, // Incluir info del contacto en contexto
    enabled: true
  });

  return response.agent;
}

    Ahora puedes crear un agente desde tu codigo Express:

    javascript
    import { createAIAgent } from './zavu.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 mensajeria WhatsApp, SMS y email
- Si no estas seguro, ofrece conectar con un agente humano
- 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:

    ProveedorModelos
    OpenAIgpt-4o, gpt-4o-mini, gpt-4-turbo
    Anthropicclaude-3-5-sonnet, claude-3-opus, claude-3-haiku
    Googlegemini-pro, gemini-1.5-pro
    Mistralmistral-large, mistral-medium
    Simplemente cambia el modelo en la configuracion de tu agente a traves del dashboard.

    Verificacion de Firma de Webhook

    Crea src/webhook.js:

    javascript
    import crypto from 'crypto';

export function verifyWebhookSignature(payload, signature) {
  const secret = process.env.ZAVU_WEBHOOK_SECRET;

  if (!signature || !secret) {
    return false;
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sha256=${expected}),
    Buffer.from(signature)
  );
}

    Crear la Ruta del Webhook

    Crea src/webhook.js:

    javascript
    import { verifyWebhookSignature } from './webhook.js';

export async function handleWebhook(req, res) {
  const signature = req.headers['x-zavu-signature'];

  // Verificar firma del webhook
  if (!verifyWebhookSignature(req.rawBody, signature)) {
    console.warn('Firma de webhook invalida');
    return res.status(401).json({ error: 'No autorizado' });
  }

  try {
    const payload = req.body;
    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 Aplicacion 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;

// Middleware para capturar body raw para verificacion de firma
app.use('/webhook', 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

  • Despliega tu app Express a un servidor con HTTPS (requerido para webhooks)
  • Configura el webhook en tu dashboard de Zavu:
    • - Ve a Senders > Selecciona tu sender > Webhook - Establece URL a: https://tudominio.com/webhook - Habilita eventos: message.inbound - Copia el secreto del webhook a tu archivo .env
  • Crea un agente de IA para tu sender en el dashboard de Zavu o via API
  • 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 configuracion de webhook de Zavu.

    Funciones del Agente Administrado

    Los agentes de IA de Zavu vienen con potentes funciones integradas, todas configurables a traves del dashboard:

    Bases de Conocimiento

    Crea respuestas potenciadas por RAG subiendo documentos para dar a tu agente conocimiento especifico del dominio.

    #### Via Dashboard

  • Ve a Senders > Selecciona tu sender > AI Agent > Knowledge Bases
  • Haz clic en Create Knowledge Base
  • Sube documentos (PDF, TXT, MD) o pega contenido directamente
  • El agente usara automaticamente 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: 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({
    senderId: senderId,
    kbId: kbId,
    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,
  'Politica de Devoluciones',
  Nuestra politica de devoluciones permite devoluciones dentro de 30 dias de la compra.

Los articulos deben estar:
- En condicion original
- Con recibo o comprobante de compra
- Sin uso o danos
);

    Herramientas Personalizadas

    Conecta APIs externas para extender las capacidades de tu agente creando herramientas que la IA puede llamar.

    #### Via Dashboard

  • Ve a Senders > Selecciona tu sender > AI Agent > Tools
  • Haz clic en Create Tool
  • 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: 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});

    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) => {
  // Verificar firma del webhook de herramienta
  const signature = req.headers['x-zavu-tool-signature'];
  const secret = process.env.ZAVU_TOOL_WEBHOOK_SECRET;

  if (signature && secret) {
    const expected = crypto
      .createHmac('sha256', secret)
      .update(req.body)
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(sha256=${expected}),
      Buffer.from(signature)
    )) {
      return res.status(401).json({ error: 'No autorizado' });
    }
  }

  try {
    const payload = JSON.parse(req.body);
    const { order_id } = payload;

    // 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 automaticamente a tu herramienta con el ID del pedido y proporcionara la respuesta.

    Analiticas

    Rastrea uso de tokens, costos y metricas de rendimiento directamente en tu dashboard de Zavu bajo la seccion Analytics.

    Usando Tus Propias Credenciales de IA (Opcional)

    Si prefieres usar tus propias credenciales de proveedor de IA para propositos de facturacion, puedes configurarlas en tu dashboard de Zavu:

  • Ve a Settings > AI Providers
  • Agrega tus API keys para OpenAI, Anthropic, Google o Mistral
  • Al crear un agente, usa provider: "openai" (o tu proveedor preferido) en lugar de provider: "zavu"

    • Esto te da control total sobre la facturacion mientras sigues beneficiandote de la API unificada y gestion de conversaciones de Zavu.

    Logica de Webhook Personalizada (Avanzado)

    Si necesitas procesamiento personalizado junto al agente de IA, puedes agregar logica en tu webhook:

    javascript
    export async function handleWebhook(req, res) {
  const signature = req.headers['x-zavu-signature'];

  if (!verifyWebhookSignature(req.rawBody, signature)) {
    return res.status(401).json({ error: 'No autorizado' });
  }

  try {
    const payload = req.body;

    if (payload.type === 'message.inbound') {
      const message = payload.data;
      const { from, text } = message;

      console.log(Mensaje de ${from}: ${text});

      // Logica personalizada
      if (text.toLowerCase() === 'human') {
        await zavu.messages.send({
          to: from,
          text: 'Conectandote con un agente humano...'
        });
      }
    }

    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 especificas del dominio
    • Crea herramientas personalizadas para integrar con tus sistemas backend
    • Construye flujos de conversacion para casos de uso especificos
    • Agrega soporte para mensajes multimedia (imagenes, documentos)
    Consulta la documentacion de Zavu para mas ejemplos y funciones avanzadas.

    Necesitas ayuda? Contactanos o unete a nuestra comunidad en Discord para soporte.

    Siguenos en redes sociales

    @zavudevZavuzavudevComunidad Discord

    Listo para comenzar?

    Comienza a usar la API de mensajeria unificada de Zavu hoy.

    Comenzar Ahora
    Construye un Agente de IA para WhatsApp con Express y Zavu | Zavu Blog | Zavu