Construye un Agente de IA para WhatsApp con Next.js y Zavu

En este tutorial, construiras un agente de IA para WhatsApp listo para produccion usando Next.js App Router 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 Next.js que:

• Recibe mensajes entrantes de WhatsApp via Route Handlers
• Verifica firmas de webhook para seguridad
• Usa los agentes de IA administrados de Zavu para respuestas inteligentes
• Aprovecha Next.js App Router y Server Actions
• Mantiene automaticamente el contexto de la conversacion

Requisitos Previos

• Node.js 18+
• Una cuenta de Zavu con credenciales de API
• Conocimiento basico de React y 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 Next.js o agregalo a uno existente:

Elige tu gestor de paquetes:

Bun (recomendado):

bash
bun install @zavudev/sdk

npm:

bash
npm install @zavudev/sdk

pnpm:

bash
pnpm add @zavudev/sdk

Luego crea el proyecto:

bash
npx create-next-app@latest whatsapp-agent
cd whatsapp-agent

Cuando se te pregunte, selecciona:

• TypeScript: Si
• ESLint: Si
• App Router: Si
• Src directory: Si
• Import alias: @/*

Estructura del Proyecto

text
whatsapp-agent/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── webhook/
│   │   │       └── route.ts
│   │   └── page.tsx
│   └── lib/
│       └── zavu.ts
├── .env.local
└── package.json

Configuracion del Entorno

Crea un archivo .env.local en la raiz de tu proyecto:

bash
ZAVUDEV_API_KEY=tu_api_key_de_zavu
ZAVU_WEBHOOK_SECRET=tu_secreto_de_webhook

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.

Inicializar el Cliente de Zavu

Crea src/lib/zavu.ts:

typescript
import Zavudev from '@zavudev/sdk';

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

Crear el Route Handler del Webhook

Crea src/app/api/webhook/route.ts:

typescript
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';
import { zavu } from '@/lib/zavu';

function verifyWebhookSignature(payload: string, signature: string): boolean {
  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)
  );
}

export async function POST(request: NextRequest) {
  try {
    const rawBody = await request.text();
    const signature = request.headers.get('x-zavu-signature')
 '';

    if (!verifyWebhookSignature(rawBody, signature)) {
      console.error('Firma de webhook invalida');
      return NextResponse.json({ error: 'No autorizado' }, { status: 401 });
    }

    const payload = JSON.parse(rawBody);
    const eventType = payload.type;

    console.log(Evento de webhook recibido: ${eventType});

    if (eventType === 'message.inbound') {
      const message = payload.data;
      console.log(Mensaje de ${message.from}: ${message.text});
    }

    return NextResponse.json({ status: 'ok' });
  } catch (error) {
    console.error('Error de webhook:', error);
    return NextResponse.json(
      { error: 'Error interno del servidor' },
      { status: 500 }
    );
  }
}

Desplegar y Configurar

Despliega tu app Next.js a Vercel o cualquier plataforma con HTTPS

Configura el webhook en tu dashboard de Zavu:

- Ve a Senders > Selecciona tu sender > Webhook - Establece URL a: https://tudominio.com/api/webhook - Habilita eventos: message.inbound - Copia el secreto del webhook a tu archivo .env.local

Crea un agente de IA para tu sender en el dashboard de Zavu

Despliega tu app:

bash
npm run build
npm start

Pruebas Locales

Para pruebas locales, usa ngrok:

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 Server Actions

Crea una server action en src/app/actions/agent.ts:

typescript
'use server';

import { zavu } from '@/lib/zavu';
import { revalidatePath } from 'next/cache';

export async function createAgent(formData: FormData) {
  const senderId = formData.get('senderId') as string;
  const name = formData.get('name') as string;
  const systemPrompt = formData.get('systemPrompt') as string;

  const response = await zavu.senders.agent.create({
    senderId,
    name,
    provider: 'zavu',
    model: 'gpt-4o-mini',
    systemPrompt,
    contextWindowMessages: 10,
    includeContactMetadata: true,
    enabled: true
  });

  revalidatePath('/dashboard');
  return response.agent;
}

export async function getAgentStats(senderId: string) {
  const response = await zavu.senders.agent.stats(senderId);
  return response;
}

Bases de Conocimiento

Crea una server action para bases de conocimiento en src/app/actions/knowledge-base.ts:

typescript
'use server';

import { zavu } from '@/lib/zavu';

export async function createKnowledgeBase(formData: FormData) {
  const senderId = formData.get('senderId') as string;
  const name = formData.get('name') as string;
  const description = formData.get('description') as string;

  const response = await zavu.senders.agent.knowledgeBases.create({
    senderId,
    name,
    description
  });

  return response.knowledgeBase;
}

export async function addDocument(formData: FormData) {
  const senderId = formData.get('senderId') as string;
  const kbId = formData.get('kbId') as string;
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  const response = await zavu.senders.agent.knowledgeBases.documents.create({
    senderId,
    kbId,
    title,
    content
  });

  return response.document;
}

Herramientas Personalizadas

Crea un endpoint de herramienta en src/app/api/tools/order-status/route.ts:

typescript
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { order_id } = body;

    const orderStatus = await getOrderFromDatabase(order_id);

    return NextResponse.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 NextResponse.json(
      { success: false, error: 'Error interno del servidor' },
      { status: 500 }
    );
  }
}

async function getOrderFromDatabase(orderId: string) {
  return {
    status: 'enviado',
    delivery_date: '2024-01-20',
    tracking_url: 'https://tracker.example.com/ORD-12345'
  };
}

Crea la herramienta via server action:

typescript
// src/app/actions/tools.ts
'use server';

import { zavu } from '@/lib/zavu';

export async function createOrderStatusTool(formData: FormData) {
  const senderId = formData.get('senderId') as string;
  const webhookUrl = https://${process.env.VERCEL_URL || 'localhost:3000'}/api/tools/order-status;

  const response = await zavu.senders.agent.tools.create({
    senderId,
    name: 'get_order_status',
    description: 'Obtener el estado actual de un pedido de cliente',
    webhookUrl,
    parameters: {
      type: 'object',
      properties: {
        order_id: {
          type: 'string',
          description: 'El ID del pedido a buscar'
        }
      },
      required: ['order_id']
    }
  });

  return response.tool;
}

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"

Esto te da control total sobre la facturacion mientras sigues beneficiandote de la API unificada de 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
• Agrega una UI de dashboard para administrar tus agentes

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