Construye un Agente de IA para WhatsApp con

En este tutorial, construiras un agente de IA para WhatsApp listo para producción usando Next.js App Router 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 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 automáticamente el contexto de la conversacion

Requisitos Previos

Node.js 18+
Una cuenta de Zavu con credenciales de API
Conocimiento básico 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 través de una sola integración.

Instalacion

Crea un nuevo proyecto Next.js o agregalo a uno existente:

Elige tu gestor de paquetes:

Bun (recomendado):

terminal
bun install @zavudev/sdk

npm:

terminal
npm install @zavudev/sdk

pnpm:

terminal
pnpm add @zavudev/sdk

Luego crea el proyecto:

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

Cuando se te pregunte, seleccióna:

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

Estructura del Proyecto

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

Configuración del Entorno

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

terminal
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 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.

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 inválida');
      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 > Seleccióna 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:

terminal
npm run build
npm start

Pruebas Locales

Para pruebas locales, usa ngrok:

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

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

TypeScript
'use server';

import { zavu } from '@/lib/zavu';
import { reválidatePath } 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
  });

  reválidatePath('/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 facturación 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 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 una UI de dashboard para administrar tus agentes

Consulta la documentación de Zavu para más ejemplos y funciones avanzadas.

Agentes IA

Messaging API

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