---
title: Construye un Agente de IA para WhatsApp con Next.js y Zavu
description: Aprende a construir un agente de WhatsApp potenciado por IA usando Next.js y el AI Gateway administrado de Zavu.
date: 2025-12-23
author: Victor Villalobos
locale: es
source: https://www.zavu.dev/es/blog/whatsapp-ai-agents-nextjs
tags: Agentes IA, WhatsApp, Next.js, App Router
---

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

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)**:
```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, 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:

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

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

2. 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`

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

4. 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 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 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:

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"`

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](https://docs.zavu.dev) para más ejemplos y funciones avanzadas.