# VipBot - Plataforma de Automatizacion de Atencion al Publico y Ventas

## Documentacion del Proyecto - Estado al 29 de Marzo 2026

---

## 1. Vision General

Plataforma propia de atencion al cliente y ventas que reemplaza herramientas como artificialic.com y chatfuel. Integra WhatsApp Business, Instagram, Messenger y un chatbot web, todo gestionado desde un dashboard unificado con soporte multi-negocio.

### Arquitectura

```
              +----------------------------------+
              |       Meta Platform APIs          |
              |  (WhatsApp Cloud API, Messenger,  |
              |   Instagram Messaging)            |
              +----------+-----------------------+
                         | Webhooks
                         v
  +----------+    +-------------+    +------------------+
  | Web Chat |--->|  VipBot API |--->|      n8n         |
  | Widget   |    |  (Node.js)  |    | (Flujos/Workflows)|
  | (embed)  |    |  Puerto 4000|    |  Puerto 5678     |
  +----------+    +------+------+    +------------------+
                         |
                +--------+--------+
                | Agent Dashboard |
                | (Next.js :4001) |
                | Inbox unificado |
                +--------+--------+
                         |
                 +-------+--------+
                 |  MariaDB       |
                 |  Redis         |
                 +----------------+
```

---

## 2. Lo que ya esta instalado y funcionando (Fase 1 COMPLETADA)

### n8n v2.8.4
- **URL**: https://n8n.mardenli.com/
- **Puerto interno**: 5678
- **Cuenta admin**: ya creada (email: neracosu@gmail.com)
- **Licencia**: Community Edition activada
- **Proceso**: Corriendo via PM2 (id: 2)

### Archivos de configuracion

#### PM2 Ecosystem: `/home/mardenli/n8n-ecosystem.config.js`
```javascript
module.exports = {
  apps: [{
    name: 'n8n',
    script: '/home/mardenli/.npm-global/bin/n8n',
    args: 'start',
    env: {
      N8N_HOST: '0.0.0.0',
      N8N_PORT: 5678,
      N8N_PROTOCOL: 'https',
      WEBHOOK_URL: 'https://n8n.mardenli.com/',
      N8N_EDITOR_BASE_URL: 'https://n8n.mardenli.com/',
      NODE_ENV: 'production',
      N8N_ENCRYPTION_KEY: '495b18801c01817428e590ecacb5db3beb2d04ca6cf4925352727e6b6bdcf3e3',
      GENERIC_TIMEZONE: 'America/New_York'
    },
    max_memory_restart: '1G',
    autorestart: true,
    watch: false
  }]
};
```

#### n8n Config: `/home/mardenli/.n8n/config.json`
```json
{
  "executions": {
    "process": "main",
    "saveDataOnError": "all",
    "saveDataOnSuccess": "all"
  },
  "generic": {
    "timezone": "America/New_York"
  }
}
```

#### Apache Proxy: `/home/mardenli/public_html/n8n.mardenli.com/.htaccess`
```apache
# n8n reverse proxy to port 5678
DirectoryIndex disabled
RewriteEngine On

# Exclude Let's Encrypt / AutoSSL verification
RewriteCond %{REQUEST_URI} !^/\.well-known/
RewriteCond %{REQUEST_URI} !^/cgi-bin/

# WebSocket support
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^(.*)$ ws://127.0.0.1:5678/$1 [P,L]

# Regular HTTP proxy
RewriteRule ^(.*)$ http://127.0.0.1:5678/$1 [P,L]
```

### Base de datos
- **MariaDB 10.11** ya tiene la base `mardenli_vipbot` creada
- **Usuario**: mardenli_vipbot
- **n8n usa SQLite** internamente (datos en `/home/mardenli/.n8n/`)

### Puertos en uso
| Servicio | Puerto | URL |
|----------|--------|-----|
| sportsbook (Next.js) | 3000 | loscaracas.mardenli.com |
| bowling (Next.js) | 3003 | auditarsp.mardenli.com |
| n8n | 5678 | n8n.mardenli.com |
| VipBot API (pendiente) | 4000 | vipbot.mardenli.com/api/ |
| Dashboard (pendiente) | 4001 | vipbot.mardenli.com/ |

### Servidor
- **OS**: Ubuntu 22.04 LTS
- **cPanel/WHM** con Apache
- **12 cores / 47 GB RAM / 262 GB disco libre**
- **Node.js 20.20.0**, npm 10.8.2
- **Redis 6.0** disponible
- **PM2** instalado globalmente

### PENDIENTE - PM2 auto-inicio
Ejecutar con acceso root para que PM2 sobreviva reinicios del servidor:
```bash
sudo env PATH=$PATH:/usr/bin /home/mardenli/.npm-global/lib/node_modules/pm2/bin/pm2 startup systemd -u mardenli --hp /home/mardenli
```

---

## 3. Fase 2 - Integracion Meta (PENDIENTE - Proximo paso)

### Paso 1: Crear Meta App
1. Ir a https://developers.facebook.com/apps/
2. Click "Create App"
3. Seleccionar tipo: **Business**
4. Seleccionar el Business Portfolio verificado existente
5. Nombrar la app (ej: "VipBot Automation")

### Paso 2: Configurar WhatsApp Cloud API
1. En la app creada, ir a "Add Products" > seleccionar **WhatsApp**
2. Ir a WhatsApp > **API Setup**
3. Anotar:
   - **Phone Number ID** (ej: 1234567890)
   - **WhatsApp Business Account ID** (ej: 9876543210)
4. Para el token permanente:
   - Ir a Business Settings > **System Users**
   - Crear un System User (tipo Admin)
   - Asignarle la app con permisos completos
   - Generar token con estos permisos:
     - `whatsapp_business_messaging`
     - `whatsapp_business_management`
   - **GUARDAR EL TOKEN** (solo se muestra una vez)

### Paso 3: Configurar Messenger
1. En la app, ir a "Add Products" > seleccionar **Messenger**
2. En Messenger Settings > **Access Tokens**:
   - Conectar la Pagina de Facebook del negocio
   - Generar Page Access Token
3. En **Webhooks**:
   - URL del webhook: `https://n8n.mardenli.com/webhook/messenger`
   - Verify Token: elegir una frase secreta (ej: "vipbot_verify_2026")
   - Suscribir a: `messages`, `messaging_postbacks`, `messaging_optins`

### Paso 4: Configurar Instagram Messaging
1. La cuenta de Instagram debe estar en modo **Professional/Business**
2. Debe estar **conectada a la Pagina de Facebook** del negocio
3. En la app de Meta, el producto Messenger ya incluye Instagram
4. En Messenger Settings > Instagram:
   - Conectar la cuenta de Instagram
5. En Webhooks, suscribir tambien a: `instagram_messaging`

### Paso 5: Configurar Webhooks en n8n
1. Abrir n8n (https://n8n.mardenli.com/)
2. Crear workflow "Meta Webhooks"
3. Agregar nodo **Webhook** con estas rutas:
   - `/webhook/whatsapp` - para WhatsApp
   - `/webhook/messenger` - para Messenger
   - `/webhook/instagram` - para Instagram (o usar el mismo de Messenger)
4. Cada webhook debe:
   - Responder al GET de verificacion de Meta (challenge response)
   - Procesar los POST con mensajes entrantes

### Paso 6: Registrar Webhooks en Meta
1. En la app de Meta > WhatsApp > Configuration:
   - Callback URL: `https://n8n.mardenli.com/webhook/whatsapp`
   - Verify Token: la frase secreta elegida
   - Suscribir a: `messages`
2. Para Messenger/Instagram ya se configuro en el paso 3

### Datos que necesitaras tener a mano:
- [ ] App ID de Meta
- [ ] App Secret de Meta
- [ ] WhatsApp Phone Number ID
- [ ] WhatsApp Business Account ID
- [ ] System User Permanent Token
- [ ] Page Access Token (para cada pagina)
- [ ] Verify Token (tu frase secreta)
- [ ] Cuentas de Instagram conectadas a las paginas

---

## 4. Fases Futuras (Resumen)

### Fase 3 - Widget Web Chat (Semana 2-3)
- Widget embebible via `<script>` tag
- Backend API con WebSocket (Socket.io + Redis)
- Persistencia en MariaDB (mardenli_vipbot)

### Fase 4 - Dashboard de Agentes (Semana 3-4)
- Next.js en vipbot.mardenli.com
- Inbox unificado (WhatsApp, Messenger, Instagram, Web)
- Asignacion de agentes, respuestas predefinidas
- Multi-tenant: selector de unidad de negocio

### Fase 5 - Flujos de Automatizacion en n8n (Semana 4-5)
- Bienvenida automatica
- FAQ automatizado
- Embudo de ventas
- Agendamiento de citas
- Escalamiento a agente humano
- Encuestas CSAT
- Horarios de atencion
- Broadcasts/campanas

---

## 5. Arquitectura Multi-Negocio

Cada unidad de negocio tendra:
- Sus propias credenciales Meta (numero WhatsApp, Page token, Instagram)
- Su propio token de widget web
- Sus propios flujos en n8n
- Su propio equipo de agentes
- Filtrado por `business_unit_id` en base de datos compartida

---

## 6. Comandos utiles

```bash
# Ver estado de n8n
pm2 status n8n

# Ver logs de n8n
pm2 logs n8n --lines 50

# Reiniciar n8n
pm2 restart n8n

# Verificar que n8n responde
curl -s -o /dev/null -w "%{http_code}" http://localhost:5678/

# Conectar a la base de datos
mysql -u mardenli_vipbot -p mardenli_vipbot

# PM2 path (si no lo encuentra)
export PATH=$PATH:/home/mardenli/.npm-global/bin
```

---

## 7. Directorio del proyecto
```
/home/mardenli/
  ├── n8n-ecosystem.config.js          # PM2 config para n8n
  ├── .n8n/                            # Datos internos de n8n (SQLite, etc)
  │   └── config.json
  ├── public_html/
  │   ├── n8n.mardenli.com/            # Subdominio de n8n
  │   │   └── .htaccess                # Proxy reverso Apache -> :5678
  │   └── vipbot.mardenli.com/         # Proyecto VipBot (futuro dashboard + API)
  │       └── DOCS-VIPBOT-PROJECT.md   # Este archivo
  └── .pm2/
      └── dump.pm2                     # Estado guardado de PM2
```