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_meta",
  "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. Acá no hay default: es explícito.
content	object	Sí	Solo texto: { "type": "text", "text": "..." } (1–10.000 caracteres).
whatsappAccountId	string (UUID)	Depende	Opcional: solo si tenés más de una cuenta conectada.
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_meta",
    "content": { "type": "text", "text": "Hola! Este mes 2x1 en turnos." },
    "whatsappAccountId": "TU_ACCOUNT_ID"
  }'

Warning

Para iniciar conversaciones fuera de la ventana de 24 hs, Meta exige plantillas aprobadas. Enviá solo a contactos que dieron su consentimiento: la calidad del número depende de ello.