# WhatsApp gratis para test de campañas — Guía XZonas

> **Proyecto:** `chatbot-unified` · **Panel:** `panel/whatsapp_hub.php`  
> **Última actualización:** 2026-07-03

---

## Resumen rápido

| Opción | Coste | Ideal para | Riesgo |
|--------|-------|------------|--------|
| **DRY_RUN** (ya integrado) | Gratis | Desarrollo local, lógica campaña | Ninguno |
| **Meta Cloud API** | 1000 conv/mes gratis | Producción oficial | Bajo si cumples políticas |
| **Evolution API** (integrado) | Software gratis + VPS ~5€/mes | Test real sin Meta Business | Medio (no oficial) |
| **Baileys / WPPConnect** | Gratis (self-host) | Control total dev | Medio-alto |

**Recomendación sin número WhatsApp Business:** activa `WHATSAPP_DRY_RUN=true` hoy y despliega Evolution API en Tailscale para pruebas reales con QR.

---

## 1. Modo DRY_RUN (ya funciona)

En `.env` raíz o variables de entorno:

```env
WHATSAPP_DRY_RUN=true
WHATSAPP_DRY_RUN_MODE=success
```

- Simula envíos sin API ni número.
- Los logs van a `chatbot/logs/chatbot.log`.
- Panel: **Hub WhatsApp → Test campaña sandbox**.

---

## 2. Meta Cloud API (oficial, tier gratis)

### ¿Puedo crear cuenta WhatsApp gratis?

**Sí, parcialmente:**
1. Crea cuenta en [Meta Developers](https://developers.facebook.com/).
2. Crea app → producto **WhatsApp**.
3. Obtienes **número de prueba** y hasta **5 destinatarios** de test sin verificar negocio.
4. En producción: WABA verificada + número dedicado (no puede estar en WhatsApp personal).

### Variables

```env
WHATSAPP_PROVIDER=meta
WHATSAPP_TOKEN=tu_token_largo
WHATSAPP_PHONE_NUMBER_ID=123456789
WHATSAPP_VERIFY_TOKEN=token_webhook_secreto
WHATSAPP_DRY_RUN=false
```

### Límites gratis Meta (2026)

- ~1000 conversaciones de servicio gratis/mes (según categoría).
- Plantillas marketing: requieren aprobación Meta.
- Opt-in obligatorio para campañas (tabla `whatsapp_consents`).

---

## 3. Evolution API (open source — integrado en este proyecto)

[Evolution API](https://github.com/evolutionapi/evolution-api) emula WhatsApp Web (Baileys). Es **gratis como software** (Apache 2.0).

### Instalación rápida (Docker + Tailscale)

```bash
# En tu VPS o PC con Docker
docker run -d --name evolution \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=mi_clave_secreta \
  atendai/evolution-api:latest
```

1. Abre `http://TU_IP_TAILSCALE:8080/manager`
2. Crea instancia `xzonas`
3. Escanea QR con WhatsApp (usa número secundario, no el personal de producción)

### Variables en `.env` del chatbot

```env
WHATSAPP_PROVIDER=evolution
WHATSAPP_DRY_RUN=false
EVOLUTION_API_URL=http://100.x.x.x:8080
EVOLUTION_API_KEY=mi_clave_secreta
EVOLUTION_INSTANCE=xzonas
```

### Endpoints usados por el proyecto

- `POST /message/sendText/{instance}` — texto
- `POST /message/sendTemplate/{instance}` — plantillas
- `GET /instance/connectionState/{instance}` — estado conexión

### Riesgos

- Método no oficial → posible ban si abusas de volumen comercial.
- Solo para **test y desarrollo**; producción masiva → Meta Cloud API.

---

## 4. Otras opciones open source

| Herramienta | Tipo | Notas |
|-------------|------|-------|
| [Baileys](https://github.com/WhiskeySockets/Baileys) | Librería TS | Máximo control, más código |
| [WPPConnect](https://github.com/wppconnect-team/wppconnect) | Librería/servicio | Entre Baileys y Evolution |
| [Venom-bot](https://github.com/orkestral/venom) | Librería Node | Bots simples |
| Green API | SaaS freemium | QR rápido, límites en free tier |

---

## 5. Integración en el frontend (Hub WhatsApp)

**URL panel:** `chatbot-unified/panel/whatsapp_hub.php`

Funciones:
- Selector visual de proveedor (Meta / Evolution / DRY_RUN)
- Test envío individual
- Test campaña sandbox (hasta 5 números)
- Estado en vivo + supervisor IA
- Enlace **Cursor Bridge móvil** (Tailscale `100.78.198.98:8095`)

**API:** `chatbot-unified/api/whatsapp_hub_api.php`

| Acción | Método | Parámetros |
|--------|--------|------------|
| `status` | GET | — |
| `test_send` | POST | phone, message |
| `test_campaign` | POST | phones (coma), message |
| `agent_recommend` | POST | task |

---

## 6. Agentes del servidor (Supervisor)

Config: `chatbot-unified/config/supervisor.secrets.php`

```php
return [
    'base_url' => 'http://100.69.11.89:8787',
    'api_token' => 'TU_TOKEN',
    'bridge_url' => 'http://100.78.198.98:8095',
    'default_project' => 'chatbot',
];
```

- **Supervisor:** recomienda plantilla de agente (`ops`, etc.)
- **Bridge móvil:** continúa tareas desde el móvil vía Tailscale
- Auth local/Tailscale: IPs `100.x.x.x` entran automáticamente (`auth_loader.php`)

---

## 7. Bridge móvil — chat sin fallos

### Auth Tailscale (ya reparado)

- `chatbot/includes/dashboard/auth_loader.php` — fuente única
- Rutas symlink: `admin/`, `includes/`, `chatbot-unified/includes/`
- Acceso auto en `localhost` y red `100.x.x.x`

### URLs útiles vía Tailscale

| Recurso | Ruta |
|---------|------|
| Dashboard | `/chatbot/chatbot-unified/panel/dashboard.php` |
| Hub WhatsApp | `/chatbot/chatbot-unified/panel/whatsapp_hub.php` |
| Asistente IA | `/chatbot/chatbot-unified/panel/ai_assistant.php` |
| Bridge Cursor | `http://100.78.198.98:8095` |

### Checklist móvil

- [ ] Tailscale activo en móvil y PC
- [ ] XAMPP Apache corriendo
- [ ] `WHATSAPP_DRY_RUN=true` para pruebas sin número
- [ ] Panel responsive (`panel-shell.css` sidebar colapsable)
- [ ] Botones touch ≥44px en Hub WhatsApp

---

## 8. Cron campañas reales

```bash
# Unified marketing
php chatbot-unified/cron/send_marketing_messages.php

# Legacy bulk
php chatbot/bulk_cron.php
```

Ambos usan `WhatsAppGateway` → respetan `WHATSAPP_PROVIDER`.

---

## 9. Troubleshooting

| Error | Solución |
|-------|----------|
| `auth_loader.php` not found | Verificar `admin/includes/dashboard/auth_loader.php` existe |
| Evolution `connectionState` closed | Re-escanear QR en Evolution manager |
| Meta 403 webhook | Revisar `WHATSAPP_VERIFY_TOKEN` en `webhook.php` |
| Todos `skipped_no_consent` | Importar CSV con `opt_in=1` o registrar en `whatsapp_consents.php` |
| Supervisor offline | Completar `api_token` en `supervisor.secrets.php` |

---

## Referencias

- [WHATSAPP_FULL_ROADMAP.md](./WHATSAPP_FULL_ROADMAP.md)
- [README_STAGING.md](../../chatbot/README_STAGING.md)
- [Evolution API GitHub](https://github.com/evolutionapi/evolution-api)
- Panel Hub: `panel/whatsapp_hub.php`