WAPI - WhatsApp API Gateway

Dashboard y API para integrar WhatsApp en tus aplicaciones. Conecta múltiples cuentas de WhatsApp, envía mensajes via API y recibe webhooks cuando llegan mensajes.

✨ Características

📱 Gestión de Cuentas WhatsApp

• Conecta múltiples cuentas de WhatsApp via QR code
• Dashboard para administrar todas tus cuentas
• Estado de conexión en tiempo real
• Almacenamiento de sesiones persistente

🔗 Conexiones (Integraciones)

Cada cuenta de WhatsApp puede tener múltiples "conexiones", que son integraciones bidireccionales:

📤 Sender (Enviar mensajes via API)

• API REST para enviar mensajes
• Autenticación via Bearer token
• Soporte para mensajes de texto, imágenes, documentos, etc.
• Endpoint: POST /api/{whatsapp_slug}/{connection_slug}/sender

📥 Receiver (Webhooks)

• Recibe mensajes entrantes via webhook
• Configura URLs personalizadas para cada conexión
• Headers personalizados para autenticación
• Payload completo del mensaje incluyendo metadatos

👥 Gestión de Contactos y Grupos

• Sincronización automática de contactos
• Gestión de grupos de WhatsApp
• Historial de mensajes por chat

🔐 Sistema de Usuarios

• Autenticación segura con Better Auth
• Roles de usuario (admin/user)
• Registro público deshabilitado (solo admins crean usuarios)
• API de administración para gestión de usuarios

💬 Chat en Tiempo Real

• Visualización de chats y mensajes
• Actualizaciones via Server-Sent Events (SSE)
• Historial de mensajes almacenado en base de datos
• Soporte multimedia completo: imágenes, videos, audio, stickers y documentos
• Tracking de estados de entrega: pendiente, enviado, entregado y leído
• Almacenamiento de archivos multimedia en el servidor

🛠️ Stack Tecnológico

• Framework: Next.js 16 (App Router)
• Base de datos: SQLite / Turso (LibSQL)
• ORM: Drizzle ORM
• WhatsApp: Baileys
• Autenticación: Better Auth
• UI: Tailwind CSS + shadcn/ui
• Validación: Zod

🚀 Instalación

Prerrequisitos

• Node.js 20+
• pnpm

1. Clonar e instalar dependencias

git clone <repo-url>
cd wapi
pnpm install

2. Configurar variables de entorno

Copia el archivo de ejemplo y configura tus valores:

cp .env.example .env

Variables requeridas:

# Base de datos (SQLite local o Turso)
DATABASE_URL=file:local.db
DATABASE_AUTH_TOKEN=

# Better Auth
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=tu-clave-secreta-minimo-32-caracteres

# Entorno
NODE_ENV=development

3. Crear tablas en la base de datos

pnpm db:push

4. Crear carpeta para archivos multimedia

mkdir -p public/media

La carpeta public/media almacenará los archivos multimedia (imágenes, videos, audio, documentos) recibidos en los mensajes. Los archivos se organizan por cuenta de WhatsApp y fecha.

5. Crear usuario administrador

pnpm db:seed

Credenciales por defecto:

• Email: [email protected]
• Password: Admin123!

5. Iniciar el servidor

pnpm dev

Abre http://localhost:3000

📖 Uso

Conectar una cuenta de WhatsApp

1. Inicia sesión en el dashboard
2. Crea una nueva cuenta de WhatsApp
3. Escanea el código QR con tu teléfono
4. ¡Listo! La cuenta está conectada

Mensajes Multimedia

El sistema soporta los siguientes tipos de mensajes:

• Texto: Mensajes de texto estándar
• Imágenes: JPG, PNG, WebP (se muestran en el chat)
• Videos: MP4, MKV, etc. (reproductor integrado)
• Audio: OGG, MP3, etc. (reproductor de audio)
• Stickers: Stickers de WhatsApp
• Documentos: PDF, DOCX, etc. (enlace de descarga)

Los archivos multimedia se almacenan en public/media/{whatsapp_id}/{YYYY-MM-DD}/{message_id}_{filename} y son accesibles vía URL pública.

Estados de Entrega (ackStatus)

Cada mensaje tiene un estado de entrega que se actualiza en tiempo real:

• 0: Pendiente (⏱) - El mensaje está en cola o falló
• 1: Enviado (✓) - El mensaje fue enviado al servidor de WhatsApp
• 2: Entregado (✓✓) - El mensaje fue entregado al destinatario
• 3: Leído (✓✓ azul) - El destinatario leyó el mensaje

Los estados se actualizan automáticamente vía SSE y se reflejan en la interfaz de chat.

Requisitos de Almacenamiento

• Los archivos multimedia se almacenan en el sistema de archivos del servidor
• Considera el espacio en disco disponible según el volumen de mensajes multimedia
• Recomendado: al menos 10 GB libres para uso normal
• Para producción: considerar una solución de almacenamiento escalable (S3, Cloud Storage, etc.)

Crear una conexión (integración)

1. Ve a la cuenta de WhatsApp
2. Crea una nueva conexión
3. Configura el Sender (para enviar mensajes):
   • Habilita el sender
   • Copia el token generado
4. Configura el Receiver (para recibir mensajes):
   • Habilita el receiver
   • Ingresa la URL de tu webhook
   • Agrega headers si es necesario

Enviar mensajes via API

curl -X POST "http://localhost:3000/api/{whatsapp_slug}/{connection_slug}/sender" \
  -H "Authorization: Bearer {tu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "1234567890",
    "message": { "text": "Hola desde WAPI!" }
  }'

Formato del webhook (mensajes entrantes)

Tu endpoint recibirá un POST con este formato:

{
  "messages": [
    {
      "key": {
        "remoteJid": "[email protected]",
        "fromMe": false,
        "id": "MESSAGE_ID"
      },
      "message": {
        "conversation": "Hola!"
      },
      "messageTimestamp": 1704470400,
      "pushName": "Nombre del contacto"
    }
  ],
  "type": "notify"
}

📁 Estructura del Proyecto

src/
├── app/
│   ├── api/
│   │   ├── [whatsapp_slug]/[connection_slug]/sender/  # API para enviar
│   │   ├── admin/users/create/                        # API admin
│   │   ├── auth/                                      # Better Auth
│   │   └── whatsapp/[id]/qr/                         # SSE para QR
│   ├── whatsapp/[slug]/                              # Dashboard WhatsApp
│   │   ├── connections/[connectionSlug]/             # Gestión conexiones
│   │   └── chats/                                    # Visualizar chats
│   └── login/                                        # Página de login
├── components/ui/                                    # Componentes shadcn
├── db/
│   ├── schema/                                       # Esquema Drizzle
│   └── seed.ts                                       # Seeder
├── lib/
│   ├── auth.ts                                       # Configuración Better Auth
│   ├── whatsapp.ts                                   # Lógica Baileys
│   └── whatsapp-utils.ts                             # Utilidades
└── config/                                           # Variables de entorno

🔧 Scripts Disponibles

Comando	Descripción
pnpm dev	Inicia el servidor de desarrollo
pnpm build	Compila para producción
pnpm start	Inicia el servidor de producción
pnpm db:push	Aplica el esquema a la base de datos
pnpm db:studio	Abre Drizzle Studio
pnpm db:seed	Crea el usuario admin
pnpm lint	Ejecuta ESLint

�️ Roadmap

Consulta el CHANGELOG.md para ver las características planeadas. Algunas de las próximas mejoras incluyen:

Receiver Filter Avanzado

El filtro de receiver actual solo soporta JSON estático. Próximamente:

• Evaluación JavaScript: Escribir funciones JS que evalúen mensajes

  (msg) => !msg.key.fromMe && msg.message?.conversation?.includes("pedido")

• Plantillas HTTP: Validar mensajes contra una API externa antes de enviar el webhook

  {
    "type": "http",
    "url": "https://mi-api.com/validate",
    "expectStatus": 200
  }

Otras Mejoras Planeadas

• 📊 Métricas y estadísticas de uso
• 🔄 Retry automático de webhooks fallidos
• 📝 Templates de mensajes reutilizables
• 🔗 Transformadores de payload personalizados
• ⏰ Mensajes programados
• 🔐 Seguridad avanzada (HMAC, IP whitelist)
• 🤖 Integraciones nativas (n8n, Zapier)
• 💬 Respuestas automáticas configurables

� Despliegue

Docker y Kubernetes

Este proyecto está listo para desplegarse en contenedores Docker y en clusters de Kubernetes (k8s, k3s, minikube, etc.):

Docker Local

# Desarrollo con hot reload
docker-compose --profile dev up wapi-dev

# Producción
docker-compose up

Kubernetes

# Despliegue completo (construir, subir, desplegar)
IMAGE_NAME=your-registry/wapi IMAGE_TAG=v1.0.0 ./deploy.sh full

# Ver estado
./deploy.sh status

# Ver logs
./deploy.sh logs

Documentación completa:

• Guía Rápida de Kubernetes - Inicio rápido
• Documentación Completa de Kubernetes - Guía detallada
• Guía Específica para k3s - Despliegue en k3s

Características del despliegue en Kubernetes:

• ✅ Multi-stage Dockerfile optimizado
• ✅ Manifiestos completos de K8s (Deployment, Service, Ingress, PVC)
• ✅ Volúmenes persistentes para sesiones y media
• ✅ ConfigMaps y Secrets para configuración
• ✅ Health checks y resource limits
• ✅ Script de despliegue automatizado
• ✅ Soporte para Kustomize

📚 Documentación Adicional

• API de Administración
• Despliegue en Kubernetes:
  • Guía Rápida
  • Documentación Completa
  • Guía para k3s - Despliegue en k3s
  • Arquitectura
  • Despliegue en Kubernetes - Arquitectura
• Checklist de Configuración
• Changelog

📝 Licencia

Privado - Todos los derechos reservados