Agente-Marketing/prisa-yachts/whatsapp_automation_spec.md

# WhatsApp Automation — Prisa Yachts LLC
## Evolution API + n8n | Zero Additional Cost
## Versión: 1.0 | 2026-05-04

---

## ARQUITECTURA GENERAL

```
Cliente envía WhatsApp
        ↓
  Evolution API
  (Docker en tu servidor)
        ↓
  Webhook → n8n.crewinghunters.com
        ↓
  n8n procesa mensaje
        ↓
  Evolution API → responde al cliente
```

**Costo adicional:** $0 — todo corre en infraestructura existente.
**Número:** Tu número personal/negocio actual (solo hay que escanearlo con QR una vez).

---

## PASO 1: INSTALAR EVOLUTION API

### Opción A — Docker Compose (recomendado)

En tu servidor, crear el archivo `/opt/evolution-api/docker-compose.yml`:

```yaml
version: "3.7"

services:
  evolution-api:
    image: atendai/evolution-api:latest
    container_name: evolution-api
    restart: always
    ports:
      - "8080:8080"
    environment:
      - SERVER_URL=https://wa.crewinghunters.com   # subdominio que apuntes a este servidor
      - AUTHENTICATION_TYPE=apikey
      - AUTHENTICATION_API_KEY=PRISA_WA_SECRET_KEY_AQUI
      - AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true
      - QRCODE_LIMIT=30
      - WEBHOOK_GLOBAL_ENABLED=true
      - WEBHOOK_GLOBAL_URL=https://n8n.crewinghunters.com/webhook/prisa-whatsapp
      - WEBHOOK_EVENTS_MESSAGES_UPSERT=true
      - WEBHOOK_EVENTS_MESSAGES_UPDATE=true
      - WEBHOOK_EVENTS_CONNECTION_UPDATE=true
      - DATABASE_ENABLED=false
      - CACHE_REDIS_ENABLED=false
    volumes:
      - evolution_instances:/evolution/instances

volumes:
  evolution_instances:
```

```bash
cd /opt/evolution-api
docker-compose up -d
```

### Conectar tu número (una sola vez)

```bash
# 1. Crear instancia
curl -X POST https://wa.crewinghunters.com/instance/create \
  -H "apikey: PRISA_WA_SECRET_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "prisa-yachts", "qrcode": true}'

# 2. Obtener QR
curl https://wa.crewinghunters.com/instance/connect/prisa-yachts \
  -H "apikey: PRISA_WA_SECRET_KEY_AQUI"
# → responde con imagen QR en base64 o URL

# 3. Escanear QR desde WhatsApp en tu teléfono
#    WhatsApp → Dispositivos Vinculados → Vincular dispositivo → Escanear QR
```

Una vez escaneado, el número queda conectado. Si el servidor se reinicia, Evolution API reconecta solo usando la sesión guardada.

---

## PASO 2: CONFIGURAR NGINX (si usas reverse proxy)

```nginx
server {
    listen 80;
    server_name wa.crewinghunters.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name wa.crewinghunters.com;

    # SSL (certbot o tu certificado)
    ssl_certificate /etc/letsencrypt/live/wa.crewinghunters.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wa.crewinghunters.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

---

## PASO 3: WORKFLOWS EN n8n

### Variables de entorno (agregar en n8n)

```env
PRISA_WA_API_URL=https://wa.crewinghunters.com
PRISA_WA_API_KEY=PRISA_WA_SECRET_KEY_AQUI
PRISA_WA_INSTANCE=prisa-yachts
PRISA_OWNER_PHONE=1XXXXXXXXXX   # número del dueño en formato internacional sin +
```

---

### WA-WF1: AUTO-RESPUESTA INTELIGENTE

**Trigger:** Webhook POST en `/webhook/prisa-whatsapp`

**Lógica completa:**

```
[Webhook: recibe mensaje de Evolution API]
  → [Code: extraer remoteJid, message.conversation, pushName]
  → [Code: normalizar mensaje — trim, toLowerCase]
  → [Switch — detectar intención:]

      COTIZACIÓN ("quote", "cotiz", "precio", "cost", "how much", "cuánto")
        → [HTTP: Evolution API → enviar mensaje texto]
        → [Wait 2s]
        → [HTTP: Evolution API → enviar brochure PDF]

      TECA ("teak", "teca", "wood", "madera", "deck")
        → [HTTP: Evolution API → enviar respuesta teca + brochure teca]

      ELÉCTRICO ("electric", "eléctric", "wiring", "cable", "battery", "batería", "panel")
        → [HTTP: Evolution API → enviar respuesta eléctrico + brochure eléctrico]

      UBICACIÓN ("where", "dónde", "location", "area", "stuart", "jacksonville")
        → [HTTP: Evolution API → enviar área de servicio]

      EMERGENCIA ("emergency", "urgente", "urgent", "fire", "fuego", "smoke", "humo")
        → [HTTP: Evolution API → enviar número directo]
        → [Gmail: notificar al dueño inmediatamente]

      HOLA / SALUDO (primeras palabras: "hi", "hello", "hola", "buenos", "good")
        → [HTTP: Evolution API → enviar bienvenida]

      DEFAULT (cualquier otro mensaje)
        → [HTTP: Evolution API → enviar menú de opciones]
        → [Gmail: notificar al dueño — lead sin clasificar]
```

---

### MENSAJES EXACTOS

**BIENVENIDA** (trigger: saludo genérico o primer contacto):
```
Hi! 👋 Thanks for reaching out to *Prisa Yachts LLC*.

I'm Alberto, marine electrical technician based out of Stuart, FL — serving Stuart to Jacksonville.

What can I help you with today?

1️⃣ Request a quote
2️⃣ Teak restoration & detailing
3️⃣ Marine electrical (ABYC certified work)
4️⃣ Our service area
5️⃣ Emergency / urgent issue

Just reply with the number or describe your situation.
```

---

**COTIZACIÓN RECIBIDA** (trigger: "quote", "cotización", "precio", etc.):
```
Great — I'd love to give you a quote! 🛥️

To get you an accurate estimate, I need a few quick details:

• *What service?* (electrical, teak, detailing, batteries, washdown, or full service)
• *Boat type and length?* (e.g., 38ft sailboat, 45ft twinscrew)
• *Your marina/location?*
• *Best time to call?*

Reply here or call me directly. I'll also send you our services overview right now.
```

*(seguido del brochure PDF general)*

---

**SERVICIOS DE TECA** (trigger: "teak", "teca", "deck", "wood"):
```
Teak restoration is one of our specialties. 🌿

We handle everything from quick maintenance cycles to full recoveries — and we do an honest assessment before quoting so you know if recovery or replacement makes more sense.

*Our teak services:*
• Two-part clean + sand + oil + seal
• Before/after documentation
• Gelcoat polishing & oxidation removal
• Caulking inspection and reseam

Send me a photo of your deck and I can give you a rough idea before we even schedule a visit.

Sending you our teak & detailing brochure now 👇
```

*(seguido del brochure PDF teca)*

---

**SERVICIOS ELÉCTRICOS** (trigger: "electric", "wiring", "battery", "panel"):
```
Marine electrical is our core specialty — all work done to ABYC E-11 standards. ⚡

*What we do:*
• Full rewiring (tinned wire, proper gauge, labeled circuits)
• Lithium battery bank design & installation
• Shore power systems & inverter/charger
• Solar & alternator upgrades
• NMEA 2000 / 0183 integration
• Bilge pump, washdown, anchor windlass

We work Stuart to Jacksonville. No job too small.

Sending you our electrical services brochure now 👇
```

*(seguido del brochure PDF eléctrico)*

---

**ÁREA DE SERVICIO** (trigger: "where", "location", "area"):
```
📍 *Service Area — Prisa Yachts LLC*

We're based out of *Stuart, FL* and cover the full east coast of Florida:

• Stuart / Treasure Coast ✅
• Fort Pierce ✅
• Vero Beach ✅
• Sebastian / Brevard ✅
• Titusville / Space Coast ✅
• Daytona Beach ✅
• Jacksonville ✅

Travel fees may apply for jobs north of Daytona. Free 20-min phone consult for any location before committing.

Want to schedule a consult?
```

---

**EMERGENCIA** (trigger: "emergency", "urgent", "fire", "smoke"):
```
⚠️ *URGENT — Prisa Yachts LLC*

For an active emergency (fire, flooding, electrical failure), call me directly right now:

📞 *[PHONE_NUMBER]*

If it's an electrical emergency:
• Turn off shore power at the dock pedestal
• Turn off your main breaker
• If there's smoke, get everyone off the boat

I'm responding to your message now.
```

*(+ email automático al dueño: "URGENT: WhatsApp emergency message from [nombre] at [número]")*

---

**MENÚ DEFAULT** (cualquier mensaje no clasificado):
```
Thanks for reaching out to *Prisa Yachts LLC*! 🛥️

I want to make sure I get you to the right place. What are you looking for?

1️⃣ *Quote* — I need a price for a job
2️⃣ *Teak & Detailing* — restoration, polishing, gelcoat
3️⃣ *Marine Electrical* — wiring, batteries, solar, panels
4️⃣ *Service Area* — where do you work?
5️⃣ *Emergency* — I need help now

Reply with a number or describe your situation and I'll get back to you shortly.

— Alberto | Prisa Yachts LLC | Stuart to Jacksonville
```

---

### WA-WF2: NOTIFICACIÓN DE LEAD AL DUEÑO

**Trigger:** Todos los mensajes entrantes (paralelo a WA-WF1)

**Flujo:**
```
[Webhook: recibe mensaje]
  → [Code: formatear — nombre, número, texto, hora ET]
  → [Code: ¿es número propio? → IF sí → NoOp (ignorar mensajes del dueño)]
  → [Gmail: enviar a alro65@gmail.com]
```

**Formato del email:**
```
Asunto: [Prisa Yachts WA] Nuevo mensaje — Juan Pérez

Nuevo mensaje de WhatsApp recibido:

Nombre: Juan Pérez
Número: +1 (772) 555-0123
Hora: 2026-05-04 10:32 AM ET

Mensaje:
"Hi I need a quote for my 42ft Hatteras rewiring. I'm in Fort Pierce."

---
Respuesta automática enviada: COTIZACIÓN
Brochure enviado: prisa_yachts_general.pdf

Responder: https://wa.me/17725550123
```

---

### WA-WF3: FOLLOW-UP AUTOMÁTICO (24 HORAS)

**Trigger:** Cron — cada hora, revisar leads sin respuesta humana

**Lógica:**
```
[Schedule Trigger: cada hora]
  → [Google Sheets: leer tab WALeads]
  → [Code: filtrar — status="auto_replied" AND created_at > 24h ago AND no_human_reply=true]
  → [IF hay leads pendientes]
      → [HTTP: Evolution API → enviar follow-up]
      → [Google Sheets: update status="followed_up"]
      → [Gmail: notificar al dueño]
```

**Mensaje follow-up (24h después):**
```
Hi [nombre]! Just wanted to follow up on your message yesterday about [tema]. 

Have you had a chance to think about it? I'm happy to answer any questions before you decide.

📞 Or call me directly: [PHONE_NUMBER]

— Alberto | Prisa Yachts LLC
```

---

### WA-WF4: LOG DE CONVERSACIONES (Google Sheets)

Cada mensaje recibido appenda una fila al tab `WALeads`:

| Col | Header | Ejemplo |
|-----|--------|---------|
| A | `timestamp` | `2026-05-04 10:32:00` |
| B | `phone` | `+17725550123` |
| C | `name` | `Juan Pérez` |
| D | `message` | `Hi I need a quote...` |
| E | `intent` | `quote` / `teak` / `electrical` / `emergency` / `default` |
| F | `auto_response_sent` | `yes` |
| G | `brochure_sent` | `general` / `teak` / `electrical` / `none` |
| H | `status` | `auto_replied` / `followed_up` / `converted` / `closed` |
| I | `notes` | (notas manuales del dueño) |

---

## PASO 4: API CALLS EXACTAS A EVOLUTION API

### Enviar mensaje de texto:
```
POST https://wa.crewinghunters.com/message/sendText/prisa-yachts
Headers: apikey: PRISA_WA_SECRET_KEY_AQUI
Body: {
  "number": "17725550123",   ← sin +, sin espacios
  "text": "Hola mensaje aquí"
}
```

### Enviar documento/brochure PDF:
```
POST https://wa.crewinghunters.com/message/sendMedia/prisa-yachts
Headers: apikey: PRISA_WA_SECRET_KEY_AQUI
Body: {
  "number": "17725550123",
  "mediatype": "document",
  "mimetype": "application/pdf",
  "media": "https://drive.google.com/uc?export=download&id={FILE_ID}",
  "fileName": "PrisaYachts_Services.pdf",
  "caption": "Here's our services overview 👆"
}
```

### Enviar imagen:
```
POST https://wa.crewinghunters.com/message/sendMedia/prisa-yachts
Body: {
  "number": "17725550123",
  "mediatype": "image",
  "mimetype": "image/jpeg",
  "media": "https://...",
  "caption": "Before & After — Teak Restoration"
}
```

---

## FLUJO DE IMPLEMENTACIÓN (orden)

### Semana 1: Setup
1. [ ] Instalar Evolution API con Docker en tu servidor
2. [ ] Configurar DNS: `wa.crewinghunters.com` → IP del servidor
3. [ ] Configurar Nginx + SSL (certbot)
4. [ ] Escanear QR y conectar número
5. [ ] Verificar que el webhook llega a n8n (test con mensaje de prueba)

### Semana 2: Workflows básicos
6. [ ] Construir WA-WF2 (notificación al dueño) — mínimo viable, sin riesgo
7. [ ] Construir WA-WF4 (log en Google Sheets) — solo lectura/escritura
8. [ ] Probar con mensaje real de tu propio teléfono

### Semana 3: Respuesta automática
9. [ ] Construir WA-WF1 (auto-respuesta) — empezar solo con el menú DEFAULT
10. [ ] Agregar lógica de cotización
11. [ ] Subir brochures a Google Drive, obtener FILE_IDs
12. [ ] Conectar envío de PDFs
13. [ ] Agregar resto de intenciones (teca, eléctrico, emergencia)

### Semana 4: Follow-up
14. [ ] Construir WA-WF3 (follow-up 24h)
15. [ ] Probar flujo completo end-to-end

---

## PREGUNTAS A RESOLVER ANTES DEL PRIMER DEPLOY

1. ¿Cuál es la IP o hostname de tu servidor?
2. ¿Ya tienes Docker instalado en el servidor?
3. ¿Usas Nginx o Caddy como reverse proxy?
4. ¿Cuál es tu número de WhatsApp (formato +1XXXXXXXXXX)?
5. ¿Tienes los brochures PDF listos o hay que crearlos primero?

---

## NOTAS IMPORTANTES

**Riesgo de ban:** WhatsApp tolera la automatización con números conectados via QR siempre que:
- Los mensajes sean respuestas a conversaciones iniciadas por el cliente (no bulk messaging)
- No envíes mensajes masivos no solicitados
- El comportamiento sea similar al humano (con delays entre mensajes)
Esta arquitectura cumple todo eso — solo responde a mensajes entrantes.

**Sesión persistente:** Evolution API guarda la sesión en el volumen Docker. Si reinicias el servidor, reconecta solo en <30 segundos sin necesidad de escanear el QR de nuevo.

**Backup del QR:** Después de conectar el número, hacer backup del volumen: `docker run --rm -v evolution_instances:/data alpine tar czf - /data > evolution_backup.tar.gz`