---
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 Zavu({
  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
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 últimos 10 mensajes como contexto
    includeContactMetadata: true, // Incluir info del contacto en contexto
    enabled: true
  });

  return response.agent;
}
```

Ahora puedes crear un agente desde tu código 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 mensajería 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:

| 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/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 inválida');
    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 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;

// Middleware para capturar body raw para verificación 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

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: 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,
  '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: 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 automáticamente a tu herramienta con el ID del pedido y proporcionara la respuesta.

### Analíticas

Rastrea uso de tokens, costos y métricas de rendimiento directamente en tu dashboard de Zavu bajo la sección **Analytics**.

## Usando Tus Propias Credenciales de IA (Opcional)

Si prefieres usar tus propias credenciales de proveedor de IA para propósitos de facturación, puedes configurarlas en tu dashboard de Zavu:

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

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) {
  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}`);

      // Lógica 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 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://docs.zavu.dev) para más ejemplos y funciones avanzadas.