Bloquear a un usuario en la WhatsApp Business API: la regla de las 24 horas que nadie menciona

La semana pasada lanzamos una función de bloqueo/desbloqueo para nuestra integración con Bitrix24, la probamos con un número al azar y la vimos "funcionar" — HTTP 200, sin errores, todo en verde. Salvo que el número nunca apareció en la lista de bloqueo.

Esa tarde nos enseñó más sobre el comportamiento de bloqueo de la WhatsApp Business API que la documentación, así que aquí está todo en un solo lugar — incluida la regla que explica la mayoría de las quejas de "el bloqueo no funciona".

Primero, asegurémonos de hablar del mismo problema

Los resultados de búsqueda alrededor de este tema son un desastre porque dos problemas muy distintos comparten las mismas palabras:

• Quieres bloquear a un usuario — un spammer o un contacto abusivo que le escribe a tu negocio. De eso trata este artículo.
• WhatsApp bloqueó tu cuenta — tu número fue baneado o restringido. Problema completamente distinto (violaciones de políticas, calificaciones de calidad, herramientas no oficiales), y nada de lo que sigue te va a servir.

La API en sí es simple

La Cloud API expone una lista de bloqueo por número de teléfono de empresa. Tres operaciones, un endpoint:

• POST /{phone-number-id}/block_users — bloquear uno o más números
• DELETE a la misma ruta — desbloquear
• GET a la misma ruta — listar quién está bloqueado actualmente

El payload es solo messaging_product: "whatsapp" más un array de usuarios. Una vez bloqueado, los mensajes de ese usuario simplemente nunca te llegan — no se dispara ningún webhook, nada aterriza en tu bandeja ni en tu CRM. Del lado de esa persona, la entrega se detiene silenciosamente en una palomita gris.

Hasta aquí, todo obvio. Ahora las partes que de verdad muerden.

Regla 1: solo puedes bloquear a quien te escribió en las últimas 24 horas

Esta es la grande, sacada directo de la documentación de Meta pero rara vez visible en las herramientas:

Solo puedes bloquear a usuarios que le hayan escrito a tu negocio en las últimas 24 horas.

No puedes bloquear preventivamente un número que no te ha escrito. No puedes bloquear a alguien cuyo spam llegó hace tres días. La ventana es la misma ventana de atención al cliente de 24 horas que gobierna las respuestas libres — el bloqueo se trata como parte de una conversación activa, no como un firewall a nivel de cuenta.

En la práctica, esto significa que el bloqueo funciona exactamente cuando más lo necesitas (un spammer en plena ráfaga) y se niega a funcionar cuando haces limpieza ("déjame bloquear a todos los que nos spamearon el mes pasado" — no).

Regla 2: una respuesta 200 no significa que se haya bloqueado a nadie

Aquí está la respuesta que nos engañó. Las solicitudes de bloqueo son por número: la llamada a la API puede tener éxito en conjunto mientras cada uno de los números que contiene es rechazado. Los rechazos viajan dentro de la respuesta 200:

{
  "messaging_product": "whatsapp",
  "block_users": {
    "added_users": [],
    "failed_users": [
      {
        "input": "40740000000",
        "errors": [
          { "message": "...", "code": ... }
        ]
      }
    ]
  }
}

Si el número que intentaste bloquear no te ha escrito en las últimas 24 horas, aterriza en failed_users — y si tu integración solo revisa el estado HTTP, reportará éxito alegremente sin bloquear nada. Ese fue precisamente el bug que atrapamos en nuestra primera versión y, a juzgar por los hilos de los foros, no fuimos los primeros.

Si estás construyendo sobre esta API: trata failed_users como el resultado real, y muéstrale el motivo al humano que pulsó "bloquear".

Los demás límites, en corto

• Máximo 1,000 números por solicitud, y la lista tiene un tope de 64,000 usuarios bloqueados por número de teléfono. Generoso, pero no infinito para blancos de spam de alto volumen.
• No puedes bloquear otra cuenta de empresa — la API solo bloquea usuarios comunes.
• El bloqueo es por número de teléfono, no por WABA. Bloquea a un spammer en tu número de ventas y todavía puede escribirle a tu número de soporte.
• Meta está extendiendo el endpoint para aceptar los nuevos IDs de usuario por empresa además de números de teléfono — parte del despliegue de nombres de usuario, donde puede que ni siquiera tengas el número de teléfono de un spammer. Aplican las mismas reglas.

Un efecto secundario que conviene recordar

Un usuario bloqueado produce silencio absoluto — ni webhooks, ni eventos, nada. Ahora revisamos la lista de bloqueo como paso estándar cada vez que en soporte aparece un "dejaron de llegarme mensajes de este cliente en particular", porque un bloqueo olvidado hace meses se ve idéntico a una integración rota. Descartarlo cuesta una sola solicitud GET.

Bloquear desde dentro de Bitrix24

Si tu WhatsApp corre a través de WASync, la lista de bloqueo vive en la propia conexión: un panel de Bloqueados donde ves cada número bloqueado, agregas uno o desbloqueas. Dos decisiones de diseño salieron directamente de los fallos descritos arriba:

1. Cuando Meta rechaza un bloqueo, te mostramos el motivo real — incluida una nota en lenguaje claro sobre la regla de las 24 horas — en lugar de una palomita verde falsa.
2. La lista se lee siempre en vivo desde Meta, así que lo que ves es lo que realmente está en vigor, no una copia en caché.

El spam en WhatsApp ya es bastante molesto sin que encima tus herramientas te mientan sobre si el bloqueo funcionó.

¿Atiendes soporte por WhatsApp a través de las Líneas abiertas de Bitrix24? También te puede servir nuestra lista de verificación para mensajes que no aparecen — los bloqueos silenciosos son una de las siete causas de la lista.