---
title: Construye un Agente de IA para WhatsApp con Fastify y Zavu
description: Aprende a construir un agente de WhatsApp potenciado por IA usando Fastify 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-fastify
tags: Agentes IA, WhatsApp, Fastify, Node.js
---

# Construye un Agente de IA para WhatsApp con Fastify y Zavu

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)**:
```bash
bun install @zavudev/sdk fastify @fastify/env dotenv
```

**npm**:
```bash
npm install @zavudev/sdk fastify @fastify/env dotenv
```

**pnpm**:
```bash
pnpm add @zavudev/sdk fastify @fastify/env dotenv
```

Luego crea el proyecto:

```bash
mkdir whatsapp-agent && cd whatsapp-agent
npm init -y
```

## Estructura del Proyecto

```
whatsapp-agent/
├── src/
│   ├── app.js
│   ├── routes/
│   │   └── 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 la Aplicación Fastify

Crea `src/app.js`:

```javascript
import 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(`Servidor corriendo en puerto ${PORT}`);
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();
```

## Crear la Ruta del Webhook

Crea `src/routes/webhook.js`:

```javascript
import 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']
    }
  };

  // Funcion auxiliar para verificar firma del webhook
  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)
    );
  }

  // Endpoint del webhook
  fastify.post('/webhook', {
    schema: webhookSchema,
    config: {
      rawBody: true // Mantener body raw para verificación de firma
    }
  }, async (request, reply) => {
    const signature = request.headers['x-zavu-signature'];
    const rawBody = request.raw.body;

    // 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(`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

1. Despliega tu app Fastify 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

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.

## Crear un Agente de IA Administrado

### Opcion 1: Via 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 y guarda

### Opcion 2: Via SDK de JavaScript

```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',
    model: model,
    systemPrompt: systemPrompt,
    contextWindowMessages: 10,
    includeContactMetadata: true,
    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, ofrece conectar con un agente humano
- Responde en el mismo idioma que el cliente`
);

console.log(`Agente creado: ${agent.id}`);
```

## Bases de Conocimiento

Crea respuestas potenciadas por RAG subiendo documentos.

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

// Crear base de conocimiento
const kb = await zavu.senders.agent.knowledgeBases.create({
  senderId: 'sender_abc123',
  name: 'FAQ de Productos',
  description: 'Preguntas frecuentes sobre nuestros productos'
});

// Agregar documentos
await zavu.senders.agent.knowledgeBases.documents.create({
  senderId: 'sender_abc123',
  kbId: kb.id,
  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.

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

// Crear una herramienta
const tool = await zavu.senders.agent.tools.create({
  senderId: '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: 'tu_secreto_de_webhook_de_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', {
  schema: {
    body: {
      type: 'object',
      properties: {
        order_id: { type: 'string' }
      },
      required: ['order_id']
    }
  }
}, async (request, reply) => {
  const { order_id } = request.body;

  // 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:

1. Ve a **Settings** > **AI Providers** en tu dashboard de Zavu
2. Agrega tus API keys para OpenAI, Anthropic, Google o Mistral
3. Al crear un agente, usa `provider: "openai"` en lugar de `provider: "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

Consulta la [documentación de Zavu](https://docs.zavu.dev) para más ejemplos y funciones avanzadas.