Construye un Agente de IA para WhatsApp con

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

text
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

Despliega tu app Fastify a un servidor con HTTPS (requerido para webhooks)

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

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 configuración de webhook de Zavu.

Crear un Agente de IA Administrado

Opcion 1: Via Dashboard de Zavu

Ve a Senders en tu dashboard de Zavu

Seleccióna 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 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:

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 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 para más ejemplos y funciones avanzadas.

Construye un Agente de IA para WhatsApp con Fastify y Zavu