Envío masivo por la API oficial de WhatsApp

Actualizado el 29/10/2026

El envío masivo por la API oficial de WhatsApp es el envío de una plantilla de marketing aprobada por Meta a una lista de personas que dieron su consentimiento para recibir mensajes de tu empresa. El volumen lo controlan tres límites: a cuántas personas puede llegar el portafolio en 24 horas, cuántos mensajes de marketing acepta recibir cada usuario y cuántos mensajes por segundo envía el número. Para destinatarios en Brasil, cada plantilla de marketing entregada cuesta R$ 0,3217 (reales brasileños) en la tabla de Meta, y las listas sin opt-in generan bloqueos y denuncias que terminan en restricciones de la cuenta.

Esta guía cubre lo que exige Meta, cómo planificar la campaña, cuánto cuesta y un ejemplo de envío en Node.js que maneja los errores que importan.

Lo que exige Meta para el envío masivo

La API no tiene un endpoint de «difusión». Cada mensaje es una llamada de envío de plantilla para un destinatario. Lo que convierte eso en campaña es tu sistema: la lista, la programación, el control de ritmo y la lectura de los estados.

Tres reglas valen para cualquier campaña:

Plantilla aprobada. Fuera de la ventana de 24 horas abierta por el cliente, solo se pueden enviar plantillas. Para promociones, ofertas y novedades, la categoría es marketing. Mira plantillas de la API de WhatsApp y cómo clasifica Meta las plantillas.
Opt-in. La empresa necesita el número del cliente y un permiso que confirme que quiere recibir sus mensajes.
Respeto al opt-out. La política exige atender todos los pedidos de dejar de recibir mensajes, hechos dentro o fuera de WhatsApp.

Opt-in: qué pide Meta y cómo registrarlo

La página Get opt-in for WhatsApp enumera tres requisitos:

Dejar claro que la persona acepta recibir comunicaciones de la empresa.
Dejar claro el nombre de la empresa de la que va a recibir mensajes.
Cumplir la legislación aplicable.

El opt-in puede ser general, sin mencionar WhatsApp específicamente, siempre que cumpla la ley local. El método queda a criterio de la empresa: sitio web, SMS, llamada con IVR o papel firmado en la tienda. Meta recomienda opt-ins separados por categoría de mensaje (pedidos, ofertas, recomendaciones), porque eso reduce el riesgo de bloqueo por mensajes inesperados. Para armar y mantener la lista, mira lista opt-in para WhatsApp.

Un texto de casilla que cumple los requisitos:

«Quiero recibir ofertas y novedades de Tienda Ejemplo por WhatsApp. Puedo darme de baja cuando quiera respondiendo BAJA.»

Guarda la prueba del consentimiento junto al contacto. Si alguna vez se impugna, ese registro muestra cuándo y cómo la persona aceptó:

{
  "wa_id": "5584999999999",
  "optin": {
    "categoria": "marketing",
    "origen": "checkout_sitio",
    "texto_aceptado": "Quiero recibir ofertas y novedades de Tienda Ejemplo por WhatsApp.",
    "aceptado_en": "2026-10-12T14:32:10-03:00",
    "ip": "200.0.0.10"
  },
  "optout": null
}

Además de la política de Meta, el tratamiento de estos datos está sujeto a la ley de protección de datos: en Brasil, la LGPD (Ley General de Protección de Datos); en otros países, la ley local correspondiente. Consulta con el área legal la base legal, el plazo de conservación y la forma de revocar el consentimiento; este artículo no es asesoría jurídica. Mira LGPD y WhatsApp para las reglas brasileñas.

Opt-out dentro de WhatsApp

Hay dos caminos de salida que tu sistema debe manejar:

Botón en la plantilla. Incluye un botón de respuesta rápida como «No quiero ofertas». Cuando el cliente lo toca, el webhook llega con type: "button" y el texto del botón en button.text. Marca el contacto como opt-out de inmediato.
Configuración del propio WhatsApp. El usuario puede dejar de recibir los mensajes de marketing de tu empresa desde la configuración de WhatsApp. Si intentas enviar igual, el webhook de estado vuelve con failed y el error 131050, según la documentación de plantillas de marketing. Trata ese error como opt-out; el webhook user_preferences también te avisa cuando un usuario deja o retoma estos mensajes.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Los límites que controlan el volumen

Límite	Cómo funciona	Error o señal	Qué hacer
Límite de mensajes del portafolio	Destinatarios únicos fuera de la ventana de atención en 24 h móviles: 250, 2.000, 10.000, 100.000 o ilimitado	Nivel actual en WhatsApp Manager y en el campo `whatsapp_business_manager_messaging_limit`	Distribuye la campaña en varios días y sigue el nivel en WhatsApp Manager
Límite de marketing por usuario	Meta limita cuántas plantillas de marketing recibe cada persona de todas las empresas, según su interacción reciente	Estado `failed` con error `131049`	No reenvíes antes de 24 horas
Velocidad de envío (throughput)	Hasta 80 mensajes por segundo por número, por defecto; los números en coexistencia con la app quedan fijos en 20	Error `130429` en la respuesta de la API	Baja el ritmo y reintenta con espera creciente
Calidad de la plantilla	Las plantillas de baja calidad se pausan: 3 horas la primera vez, 6 horas la segunda y se desactivan la tercera	Webhook de estado de la plantilla	Detén la campaña que usa la plantilla pausada

Fuentes: límites de mensajes, límites de marketing por usuario, throughput y pausa de plantillas.

Dos detalles sorprenden a quien planifica su primera campaña:

El límite es del portafolio, no del número. Todos los números de un portafolio comparten el mismo límite. Comprar más números no multiplica el alcance.
El límite por usuario no depende de ti. Aun con opt-in, parte de los destinatarios puede no recibir el mensaje porque ya recibió mucho marketing de otras empresas. Los mensajes de marketing enviados dentro de una ventana de atención abierta por la respuesta del cliente no cuentan para ese límite. El artículo sobre el error 131049 explica qué hacer.

El artículo sobre el límite de mensajes de la API de WhatsApp detalla cómo subir de nivel, y mensajes por segundo y rate limit cubre el error 130429.

El marketing pasa a la Marketing Messages API

Meta anunció que la Cloud API dejará de admitir mensajes de marketing el 13/10/2027, y que las cuentas de mensajes creadas a partir del 13/04/2027 ya no podrán enviar marketing por la Cloud API (Marketing Messages API). Después de esa fecha, las plantillas de marketing se envían por la Marketing Messages API for WhatsApp. El ejemplo de abajo sigue usando la llamada de envío de la Cloud API, que funciona hoy; planifica la migración antes del plazo con la guía de la Marketing Messages API.

Segmentación: menos contactos, más resultado

El límite por usuario tiene en cuenta la tasa de lectura reciente de la persona. En la práctica, enviar a quien no lee empeora la entrega para todos. Segmentar bien es la forma más directa de mejorar el resultado:

Recencia. Prioriza a quien compró, respondió o abrió un mensaje en los últimos meses.
Interés declarado. Usa la categoría elegida en el opt-in. Quien aceptó «pedidos» no aceptó «ofertas».
Historial de fallas. Saca los contactos con 131050 y reduce la frecuencia para quien acumula 131049.
Frecuencia. Define en tu propio sistema un tope de campañas por contacto por semana.
Personalización. Variables con el nombre, el último producto o la ciudad hacen que el mensaje sea esperado. Meta incluye los mensajes personalizados y útiles entre sus buenas prácticas de calidad.

Cuánto cuesta un envío masivo

Desde el 1/07/2025, Meta cobra por mensaje entregado y no por conversación. Para destinatarios en Brasil, la tarifa de marketing vigente desde el 1/10/2026 es de R$ 0,3217 por mensaje, y el marketing no tiene descuento por volumen (página de precios y tabla en el sitio de WhatsApp Business). Las tarifas cambian según el país del destinatario; para otros mercados, mira el precio de la API de WhatsApp por país.

Tamaño de la campaña	Costo estimado de Meta (Brasil, marketing)
1.000 entregados	R$ 321,70
10.000 entregados	R$ 3.217,00
50.000 entregados	R$ 16.085,00

Los mensajes no entregados no se cobran. Tampoco se cobran los mensajes dentro de la ventana de punto de entrada gratuito, que se abre cuando el cliente llega por un anuncio de clic a WhatsApp y dura hasta 7 días. El artículo de precio de la API de WhatsApp en Brasil trae las demás categorías y el cálculo a partir del webhook de estado, y cuánto cuesta una campaña de WhatsApp muestra cómo simular antes de enviar.

Con Vectalk no registras tarjeta en Meta: cada mensaje entregado se descuenta de tu saldo prepago en Vectalk, y Vectalk le paga a Meta. Asegúrate de que el saldo cubra la campaña antes de empezar.

Por qué las listas compradas tumban el número

Una lista comprada o «raspada» de grupos falla en el requisito más básico: esas personas nunca dieron opt-in a tu empresa. El efecto aparece en cadena:

Comentarios negativos. Meta calcula la calidad de los mensajes con base en los últimos siete días, a partir de bloqueos, denuncias, silenciamientos, archivados y motivos informados al bloquear (calidad de los mensajes).
Plantilla pausada. Con baja calidad, la plantilla entra en pausa y, a la tercera vez, se desactiva. La campaña se corta a la mitad.
Límite congelado. El aumento automático del límite exige mensajes de alta calidad en todos los números y plantillas.
Restricciones en la cuenta. La política prevé restringir el acceso o limitar el envío de quien recibe muchos comentarios negativos. La documentación de aplicación de políticas describe bloqueos de 1 o 3 días para plantillas, de 5, 7 o 30 días para cualquier mensaje, un bloqueo de la cuenta por tiempo indefinido y, por último, la desactivación permanente en la plataforma.

Cambiar de número no lo resuelve: el límite y la reputación quedan en el portafolio. El artículo sobre el número bloqueado en la API de WhatsApp muestra cómo diagnosticar y apelar, y API oficial vs. API no oficial de WhatsApp explica por qué las herramientas no oficiales de envío masivo terminan en bloqueo.

Ejemplo: envío con ritmo controlado en Node.js

Vectalk no tiene una herramienta de envío masivo en el panel: la campaña corre en tu sistema, que llama a la API una vez por destinatario. El script envía una plantilla de marketing por Vectalk a una lista ya filtrada por opt-in, con ritmo controlado y reintento ante el error de throughput. El payload es el mismo de la Cloud API.

const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const TOKEN = process.env.VECTALK_TOKEN;
const POR_SEGUNDO = 20; // muy por debajo del tope por defecto de 80 mps

const pausa = (ms) => new Promise((r) => setTimeout(r, ms));

async function enviarPlantilla(contacto, intento = 1) {
  const r = await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: contacto.wa_id,
      type: 'template',
      template: {
        name: 'oferta_semana',
        language: { code: 'es' },
        components: [
          { type: 'body', parameters: [{ type: 'text', text: contacto.nombre }] },
        ],
      },
    }),
  });

  const cuerpo = await r.json();
  if (r.ok) return { wa_id: contacto.wa_id, wamid: cuerpo.messages[0].id };

  const codigo = cuerpo.error?.code;
  if (codigo === 130429 && intento <= 5) {
    await pausa(1000 * 2 ** intento); // espera creciente
    return enviarPlantilla(contacto, intento + 1);
  }
  return { wa_id: contacto.wa_id, error: codigo ?? r.status };
}

export async function lanzarCampana(contactos) {
  const resultados = [];
  for (let i = 0; i < contactos.length; i += POR_SEGUNDO) {
    const lote = contactos.slice(i, i + POR_SEGUNDO);
    resultados.push(...(await Promise.all(lote.map((c) => enviarPlantilla(c)))));
    await pausa(1000);
  }
  return resultados; // guarda el wamid para cruzarlo después con los estados
}

La respuesta 200 de la API solo indica que el mensaje fue aceptado. La entrega, la lectura y las fallas como 131049 y 131050 llegan después, en el webhook de estado:

export function manejarEstado(estado, db) {
  if (estado.status !== 'failed') return db.actualizarEnvio(estado.id, estado.status);

  const codigo = estado.errors?.[0]?.code;
  if (codigo === 131050) db.marcarOptOut(estado.recipient_id, 'marketing');
  if (codigo === 131049) db.programarNoAntesDe(estado.recipient_id, 24 * 60 * 60 * 1000);
  db.actualizarEnvio(estado.id, 'failed', codigo);
}

Si tu lista supera unos cientos de contactos, ejecuta el envío en un worker con cola persistente, para retomarlo donde quedó si el proceso se cae.

Checklist antes de apretar «enviar»

Plantilla de marketing aprobada, con botón de baja.
Lista filtrada por opt-in de marketing y sin contactos dados de baja.
Volumen de la campaña dentro del límite actual del portafolio.
Ritmo de envío por debajo del throughput del número.
Webhook de estado registrando entregas, lecturas y fallas.
Alguien siguiendo la calidad de la plantilla en las primeras horas.

Preguntas frecuentes

¿Puedo enviar texto libre de forma masiva?

No. El texto libre solo se permite dentro de la ventana de 24 horas abierta por el cliente. Para iniciar el contacto con una lista, hace falta una plantilla. Mira la ventana de 24 horas de WhatsApp.

¿Con cuántos contactos puedo empezar?

Un portafolio nuevo llega a 250 destinatarios únicos en 24 horas fuera de la ventana de atención. La verificación de la empresa es uno de los caminos para llegar a 2.000. Después, el límite sube automáticamente con calidad y uso.

¿Se cobra un mensaje con error 131049?

Meta solo cobra los mensajes entregados. Un mensaje con estado failed no se entrega y, por lo tanto, no se cobra.

¿Puedo usar una plantilla de utilidad para una promoción, que es más barata?

No. Meta clasifica el contenido promocional como marketing y puede recategorizar la plantilla. A quien insiste le pueden convertir las plantillas de utilidad en marketing y bloquear la creación de nuevas plantillas de utilidad por un tiempo.

¿Vale la pena tener varios números para enviar más?

No para el alcance. El límite se calcula por portafolio y lo comparten todos los números. Varios números pueden tener sentido por organización (marcas, departamentos), no para esquivar el límite.

Empieza con Vectalk

Vectalk te da acceso a la API oficial con los mismos payloads y webhooks de Meta y un token para todas las cuentas. Pagas una mensualidad y mantienes un saldo prepago; cada mensaje entregado se descuenta de ese saldo y Vectalk le paga a Meta, sin tarjeta registrada en Meta. Crea tu cuenta en apps.vectalk.com.br/register o habla con el equipo en la página de contacto para planificar tu integración.

Fuentes oficiales consultadas el 29/10/2026: Get opt-in for WhatsApp, Política de Mensajes de WhatsApp Business, Límites de mensajes, Límites de marketing por usuario, Plantillas de marketing, Marketing Messages API: visión general, Throughput, Pausa de plantillas, Aplicación de políticas, Precios, Tabla de precios en el sitio de WhatsApp Business.

Pon a funcionar el WhatsApp oficial de tu empresa

Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.

Crear cuenta gratis

Leer la documentación

Envío masivo por la API oficial de WhatsApp: cómo hacerlo sin perder el número