Construye un Agente de IA para WhatsApp con Fastify y Zavu

En este tutorial, construiras un agente de IA para WhatsApp listo para produccion usando Fastify 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 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 validacion de esquemas integrada de Fastify
• 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 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

text
whatsapp-agent/
├── src/
│   ├── app.js
│   ├── routes/
│   │   └── 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 la Aplicacion 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 validacion 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 verificacion 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 invalida');
      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

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

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.

Crear un Agente de IA Administrado

Opcion 1: Via 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 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 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});

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: 'Politica de Devoluciones',
  content: 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
});

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:

Ve a Settings > AI Providers en tu dashboard de Zavu

Agrega tus API keys para OpenAI, Anthropic, Google o Mistral

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 especificas del dominio
• Crea herramientas personalizadas para integrar con tus sistemas backend
• Construye flujos de conversacion para casos de uso especificos

Consulta la documentacion de Zavu para mas ejemplos y funciones avanzadas.