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

01plazbot 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

01phone
02# Clientes VIP
03+51912345678
04+51 987 654 321
05 
0651912345678
070051923456789; +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

01# Revisar la lista primero: valida los números y no envía nada
02plazbot whatsapp broadcast -t welcome --phones ./numbers.txt --dry-run
03 
04# Enviar la plantilla a todos los números (pide confirmación)
05plazbot whatsapp broadcast -t welcome --phones ./numbers.txt
06 
07# Mismas variables para todos y 3 segundos entre mensajes
08plazbot whatsapp broadcast -t promo --phones ./numbers.txt --var amount=20 code=PROMO20 --delay 3000
09 
10# Ejecución desatendida con el resultado por número en JSON
11plazbot whatsapp broadcast -t reminder --phones ./numbers.txt --yes --json > results.json

Resultado

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

text

01  WhatsApp Broadcast (dry run)
02  ────────────────────────────────────────
03  Template: welcome
04  Recipients: 4
05  Delay: 1000ms
06  Skipped header line: "phone"
07  Skipped 1 duplicate number(s).
08 
09  1 invalid entry (not sent):
10    ✖ line 7: "12345"
11 
12    • +51912345678
13    • +51987654321
14    • +51923456789
15    • +34611222333
16 
17  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

01? Send template "welcome" to 4 number(s)? Yes
02  ✖ +34611222333: <motivo devuelto por la API>
03  ██████████████████████████████ 100% (4/4)
04 
05  Result
06  ────────────────────────────────────────
07  Sent: 3
08  Failed: 1
09  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

01{
02  "template": "welcome",
03  "results": [
04    { "phone": "51912345678", "status": "sent" },
05    { "phone": "34611222333", "status": "failed", "error": "..." }
06  ],
07  "summary": {
08    "total": 4,
09    "sent": 3,
10    "failed": 1,
11    "invalid": [
12      { "input": "12345", "line": 7, "error": "Invalid phone number \"12345\"." }
13    ],
14    "duplicates": 1
15  }
16}

Con --dry-run --json:

json

01{
02  "dryRun": true,
03  "template": "welcome",
04  "variables": [],
05  "recipients": ["51912345678", "51987654321", "51923456789", "34611222333"],
06  "summary": {
07    "total": 4,
08    "invalid": [
09      { "input": "12345", "line": 7, "error": "Invalid phone number \"12345\"." }
10    ],
11    "duplicates": 1
12  }
13}

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`

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.