# Broadcast

> Envía una plantilla de WhatsApp aprobada a una lista de números.

Fuente: https://developers.plazbot.com/whatsapp/cli/broadcast/

### Broadcast

Envía la misma plantilla aprobada a todos los números de un archivo de texto. Valida la lista antes de enviar, pide confirmación y reporta el resultado de cada número.

```bash
plazbot whatsapp broadcast -t <plantilla> --phones <archivo> [opciones]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Plantilla | `-t, --template <name>` | Sí | Nombre exacto de la plantilla aprobada en Meta |
| Lista de números | `--phones <file>` | Sí | Archivo de texto con los números (ver formato abajo) |
| Variables | `--var <name=value...>` | No | Variables del cuerpo, iguales para todos los destinatarios. Pares `nombre=valor`; un valor vacío es un error |
| Pausa | `--delay <ms>` | No | Pausa entre mensajes en milisegundos. Default: `1000` |
| Simulación | `--dry-run` | No | Valida la lista y muestra lo que se enviaría, sin enviar nada ni llamar a la API |
| JSON | `--json` | No | Imprime solo JSON en stdout |
| Confirmar | `-y, --yes` | No | Omite la confirmación (para scripts y CI) |

### Formato del archivo

Una lista simple de números en formato internacional:

```text
phone
# Clientes VIP
+51912345678
+51 987 654 321

51912345678
0051923456789; +34611222333
```

- Un número por línea, o varios separados por comas o punto y coma.
- Se ignoran las líneas vacías, las líneas que empiezan con `#` y una primera línea de encabezado (por ejemplo `phone` o `phone,name`).
- Los duplicados se envían una sola vez (se comparan ya normalizados: `+51 912 345 678` y `51912345678` son el mismo número).
- Las entradas inválidas se listan con su número de línea y no se envían.

### Ejemplos

```bash
# Revisar la lista primero: valida los números y no envía nada
plazbot whatsapp broadcast -t welcome --phones ./numbers.txt --dry-run

# Enviar la plantilla a todos los números (pide confirmación)
plazbot whatsapp broadcast -t welcome --phones ./numbers.txt

# Mismas variables para todos y 3 segundos entre mensajes
plazbot whatsapp broadcast -t promo --phones ./numbers.txt --var amount=20 code=PROMO20 --delay 3000

# Ejecución desatendida con el resultado por número en JSON
plazbot whatsapp broadcast -t reminder --phones ./numbers.txt --yes --json > results.json
```

### Resultado

Con `--dry-run` sobre el archivo de ejemplo:

```text
WhatsApp Broadcast (dry run)
────────────────────────────────────────
Template: welcome
Recipients: 4
Delay: 1000ms
Skipped header line: "phone"
Skipped 1 duplicate number(s).

1 invalid entry (not sent):
  ✖ line 7: "12345"

  • +51912345678
  • +51987654321
  • +51923456789
  • +34611222333

Dry run: 4 message(s) would be sent with template "welcome". Nothing was sent.
```

Envío real: después del resumen pide confirmación y muestra una sola línea de progreso que se actualiza. Cada número que falla se imprime con su motivo:

```text
? Send template "welcome" to 4 number(s)? Yes
✖ +34611222333: <motivo devuelto por la API>
██████████████████████████████ 100% (4/4)

Result
────────────────────────────────────────
Sent: 3
Failed: 1
Total: 4
```

Si hubo entradas inválidas también aparece `Invalid (skipped): N`. Si respondes que no a la confirmación, imprime `Aborted.` y termina con código 1.

### Salida JSON

Envío real:

```json
{
"template": "welcome",
"results": [
  { "phone": "51912345678", "status": "sent" },
  { "phone": "34611222333", "status": "failed", "error": "..." }
],
"summary": {
  "total": 4,
  "sent": 3,
  "failed": 1,
  "invalid": [
    { "input": "12345", "line": 7, "error": "Invalid phone number \"12345\"." }
  ],
  "duplicates": 1
}
}
```

Con `--dry-run --json`:

```json
{
"dryRun": true,
"template": "welcome",
"variables": [],
"recipients": ["51912345678", "51987654321", "51923456789", "34611222333"],
"summary": {
  "total": 4,
  "invalid": [
    { "input": "12345", "line": 7, "error": "Invalid phone number \"12345\"." }
  ],
  "duplicates": 1
}
}
```

`variables` es una lista de `{ "variable", "value" }`. Con `--json` no hay confirmación interactiva: pasa `--yes` para enviar.

### Código de salida

Termina con código 1 si algún envío falló o si el archivo tenía alguna entrada inválida (también con `--dry-run`). Termina con 0 solo si todos los números eran válidos y se enviaron.

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `Could not read file: ./numbers.txt` | La ruta no existe o no se puede leer | Revisa la ruta del archivo |
| `The file has no valid phone numbers.` | Ninguna entrada válida | Un número por línea en formato internacional, por ejemplo `+51912345678` |
| `Invalid --delay "abc".` | `--delay` no es un número de milisegundos | Usa por ejemplo `--delay 1000` |
| `Variable "amount" in --var has an empty value.` | Variable vacía | Pasa un valor: `--var amount=20` |
| `This action needs confirmation and there is no interactive terminal.` | Sin terminal (CI, pipe, `--json`) y sin `--yes` | Vuelve a ejecutar con `--yes` |

> **Importante:** Respeta las políticas de Meta sobre mensajes masivos. El uso indebido puede resultar en la suspensión de tu número de WhatsApp Business. Ejecuta siempre `--dry-run` antes de un envío grande.