Broadcasts por API

POST /messages/broadcast — envía un mensaje de texto a todos los contactos de una lista creada en el portal. Genera un mensaje individual por contacto (cada uno descuenta de tu cuota mensual).

Requiere plan Basic o Pro

Los planes Free y Starter no incluyen broadcasts (la API responde 403 feature_not_available). Las listas de contactos se crean y administran desde el portal, sección Listas — ver la guía de listas y broadcasts.

Request

{
  "externalId": "promo-junio-2026",
  "listId": "3f1d4e22-...",
  "channel": "whatsapp_direct",
  "content": { "type": "text", "text": "Hola! Este mes 2x1 en turnos." },
  "whatsappAccountId": "0b8e2c1a-..."
}

Campos

Campo	Tipo	Requerido	Detalle
externalId	string	Sí	Tu identificador único del broadcast (1–200 caracteres). Misma idempotencia que los mensajes.
listId	string (UUID)	Sí	ID de la lista de contactos (figura en el portal, sección Listas). Debe ser tuya (si no: 404).
channel	string	Sí	whatsapp_meta o whatsapp_direct. Acá no hay default: es explícito.
content	object	Sí	Solo texto: { "type": "text", "text": "..." } (1–10.000 caracteres).
whatsappAccountId	string (UUID)	Depende	Obligatorio para whatsapp_direct (y la cuenta debe estar Conectada). Opcional para whatsapp_meta.
ttlSeconds	int	No	Igual que en mensajes: default 7 días, máximo 30, recortado por plan.

Respuesta

201 Created (nuevo) o 200 OK (repetición idempotente):

{
  "broadcastId": "91c7aa0e-...",
  "externalId": "promo-junio-2026",
  "listId": "3f1d4e22-...",
  "messageCount": 482,
  "status": "queued"
}

messageCount es la cantidad de mensajes generados (un contacto = un mensaje). El avance se sigue desde el portal, sección Broadcasts.

Errores propios de broadcast

Además de los errores generales, este endpoint puede responder:

Status	error	Significado
400	empty_list	La lista no tiene contactos.
400	broadcast_too_large	La lista supera el tope por broadcast (5.000 destinatarios). El cuerpo incluye required y limit.
400	whatsapp_account_invalid	Cuenta faltante, inexistente o no conectada; el campo reason indica cuál (missing / not_found / not_connected).
403	feature_not_available	Tu plan no incluye broadcasts.
404	list_not_found	La lista no existe o no es de tu cuenta.
429	quota_exceeded	El broadcast completo no entra en tu cuota mensual restante (el cuerpo incluye used, required, limit y resetsAt). No se encola parcialmente: o entra todo, o nada.

Ejemplo

curl -X POST https://api.arplyx.com/messages/broadcast \
  -H "x-api-key: $ARPLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "promo-junio-2026",
    "listId": "TU_LIST_ID",
    "channel": "whatsapp_direct",
    "content": { "type": "text", "text": "Hola! Este mes 2x1 en turnos." },
    "whatsappAccountId": "TU_ACCOUNT_ID"
  }'

Warning

Con WhatsApp Direct, evitá ráfagas masivas a contactos que nunca te escribieron: aumenta el riesgo de que WhatsApp restrinja el número. Para volumen alto y notificaciones transaccionales, el canal recomendado es Meta Official.