Calidad del número en la API de WhatsApp: verde, amarillo y rojo

Actualizado el 25/10/2026

La calidad del número en la API de WhatsApp es una calificación que Meta asigna a tu número de teléfono comercial según cómo reaccionaron los destinatarios a tus mensajes en los últimos siete días. Tiene tres colores: verde (alta), amarillo (media) y rojo (baja). El color por sí solo no bloquea el envío, pero influye en el aumento del límite de mensajes y en el throughput, y si se mantiene baja puede llevar a restricciones.

Esta guía explica de dónde sale la calificación, cómo se relaciona con la calidad de cada plantilla, cómo consultarla por API y qué hacer para recuperar un número que bajó a amarillo o rojo.

Qué es la calificación de calidad del número

Según la documentación de envío de mensajes de Meta, la calidad se calcula a partir de cómo los usuarios recibieron tus mensajes en los últimos siete días, con más peso para los más recientes. Las señales son comentarios de los usuarios:

• bloqueos;
• denuncias;
• chats silenciados;
• chats archivados;
• motivos que el usuario indica al bloquear a la empresa.

La misma página advierte que los números con mucho tráfico pueden tener cambios de calidad en intervalos cortos, a veces en minutos. Una campaña mal segmentada puede bajar la calificación el mismo día.

En la API, el campo es quality_rating y los valores posibles están en la referencia de la Phone Number API:

Color	Valor en la API	En WhatsApp Manager	Qué indica
Verde	GREEN	Alta	Poco o ningún comentario negativo
Amarillo	YELLOW	Media	Los comentarios negativos empiezan a pesar; hay que actuar
Rojo	RED	Baja	Muchos comentarios negativos; riesgo de restricción
Sin calificación	NA	Pendiente	Todavía no hay datos suficientes

Calidad del número vs. calidad de la plantilla

Son dos calificaciones distintas y conviene no confundirlas.

La calidad de la plantilla se calcula para cada plantilla de mensaje según uso, comentarios e interacción. La página de calidad de plantillas describe los valores GREEN, YELLOW, RED y UNKNOWN (plantilla nueva, sin datos). Un detalle importante: además de bloqueos y denuncias, una tasa de lectura baja también baja la calificación de la plantilla.

Cuando una plantilla llega a RED, Meta la pausa automáticamente, según la página de pausa de plantillas:

Ocurrencia	Qué pasa
1.ª vez	Plantilla pausada por 3 horas
2.ª vez	Plantilla pausada por 6 horas
3.ª vez	Plantilla desactivada

Los intentos de envío de una plantilla pausada se rechazan, no se cobran y no cuentan en el límite de mensajes. Meta afirma que la pausa, al principio, no afecta al número; pero si la empresa envía con frecuencia plantillas que llegan a calidad baja, el número puede verse afectado. En la práctica, la calificación del número es el reflejo acumulado de las plantillas y las conversaciones.

Para entender cómo la categoría de la plantilla influye en la experiencia del usuario, consulta cómo Meta clasifica las plantillas.

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

Cómo afecta la calidad a los límites y al throughput

La calidad aparece en tres puntos documentados:

1. Subir a 2.000 destinatarios. Una de las vías para salir del límite inicial de 250 es enviar 2.000 mensajes entregados fuera de la ventana de atención en 30 días, con plantillas de calidad alta. Tras cualquier vía, Meta analiza la calidad de los mensajes antes de aprobar el aumento (límites de mensajes).
2. Escalado automático. Por encima de 2.000, el límite solo sube a 10.000, 100.000 e ilimitado si la empresa envía mensajes de alta calidad en todos sus números y plantillas y usó al menos la mitad del límite en los últimos 7 días.
3. Más throughput. Para pasar de 80 mensajes por segundo, el número necesita calidad amarilla o superior, además de otros requisitos (throughput).

El límite pertenece al portafolio comercial y lo comparten todos sus números. Un número con mala calidad frena el crecimiento de todos.

Estado del número: conectado, marcado, restringido

Además del color, cada número tiene un status. La documentación de números comerciales indica que el estado refleja la calidad y el límite actual, y que solo los números con estado «conectado» envían y reciben por la API. Entre los valores de la referencia están CONNECTED, FLAGGED (marcado) y RESTRICTED (restringido).

El Centro de ayuda de Meta, en el artículo sobre la calificación de calidad del número, describe el flujo del estado marcado: cuando la calidad llega a baja, el estado pasa de conectado a marcado. Si la calidad vuelve a media o alta antes del séptimo día, el número vuelve a conectado sin cambio de límite; si no, vuelve a conectado pero el límite baja un nivel. Mientras está marcado, el límite no sube.

Cómo consultar la calidad por API

Para ver el color y el estado de un número:

curl "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>?fields=quality_rating,status,whatsapp_business_manager_messaging_limit" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "quality_rating": "GREEN",
  "status": "CONNECTED",
  "whatsapp_business_manager_messaging_limit": "TIER_2K",
  "id": "106540352242922"
}

El campo antiguo messaging_limit_tier está obsoleto; usa whatsapp_business_manager_messaging_limit.

Para la calificación de una plantilla:

curl "https://graph.facebook.com/v26.0/<TEMPLATE_ID>?fields=quality_score" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Webhooks que ayudan a monitorear

Campo del webhook	Cuándo se dispara	Uso práctico
message_template_quality_update	Cambia la calificación de una plantilla	Alertar cuando una plantilla deja GREEN
message_template_status_update	Plantilla pausada, desactivada o reactivada	Detener la campaña que la usa
account_update	Infracciones de política y restricciones de la cuenta	Avisar al equipo e investigar
phone_number_quality_update	Cambia el throughput del número	Seguir las mejoras de capacidad

Ejemplo de message_template_quality_update:

{
  "entry": [{
    "id": "102290129340398",
    "time": 1674864290,
    "changes": [{
      "value": {
        "previous_quality_score": "GREEN",
        "new_quality_score": "YELLOW",
        "message_template_id": 806312974732579,
        "message_template_name": "welcome_template",
        "message_template_language": "en-US"
      },
      "field": "message_template_quality_update"
    }]
  }],
  "object": "whatsapp_business_account"
}

Como la página actual del webhook phone_number_quality_update solo habla de throughput, conviene consultar quality_rating de forma periódica (por ejemplo, cada hora durante campañas) y guardar el historial. Así ves la tendencia antes de que se convierta en problema. Para el seguimiento de entregas, revisa estados de mensaje por webhook.

Qué baja la calidad

Meta enumera buenas prácticas en la misma página de envío de mensajes. Al revés, los errores más comunes son:

• enviar a quien no dio su consentimiento (opt-in): listas compradas, contactos antiguos reunidos para otro fin;
• mensajes genéricos, poco personalizados o sin utilidad clara;
• mensajes de bienvenida abiertos, del tipo «Hola, ¿cómo estás?», sin contexto;
• demasiados mensajes en el mismo día;
• textos demasiado largos o que la persona no espera recibir;
• contenido que infringe la Política de mensajes de WhatsApp Business.

Ignorar las solicitudes de baja también pesa: quien no logra dejar de recibir mensajes tiende a bloquear y denunciar. Una base sana empieza en el registro; consulta cómo armar una lista opt-in.

Cómo recuperar un número amarillo o rojo

1. Detén las campañas de marketing en curso. Los mensajes transaccionales esperados (confirmación de pedido, código de acceso) pueden seguir.
2. Identifica qué plantilla bajó la calificación. Consulta el quality_score de cada plantilla activa y crúzalo con lo enviado en los últimos 7 días.
3. Revisa la segmentación. Quita contactos sin opt-in registrado, inactivos desde hace mucho y quienes pidieron la baja.
4. Reescribe la plantilla problemática. Deja claro quién escribe, por qué la persona lo recibe y cómo darse de baja. Editar una plantilla la devuelve a revisión.
5. Agrega un botón de baja en las plantillas de marketing y trata el clic como baja inmediata.
6. Reduce la frecuencia. Espaciar los envíos disminuye silenciados y archivados.
7. Sigue la evolución por 7 días. Como la calificación usa una ventana de siete días, la mejora llega de forma gradual.

Si, además del color, el número recibió una restricción por política, el camino es otro: la aplicación de políticas de Meta prevé bloqueos de 1 o 3 días para plantillas, de 5, 7 o 30 días para cualquier mensaje y, en casos graves, el bloqueo de la cuenta. Los detalles están en Business Support Home, dentro de Meta Business Suite.

Calidad del número con Vectalk

Vectalk es un proxy de la Cloud API oficial: los campos y webhooks son los mismos de Meta. Para consultar la calidad del número asociado a un token de instancia, usa GET /api/phone-numbers con el parámetro fields:

curl "https://apis.vectalk.com.br/api/phone-numbers?fields=id,display_phone_number,quality_rating" \
  -H "Authorization: Bearer TU_TOKEN"

GET /api/phone-numbers/list devuelve todos los números de la cuenta con quality_rating y status. Los eventos de Meta llegan a las URL que registres con POST /api/webhooks. Más detalles en la documentación de Vectalk; el registro está en apps.vectalk.com.br/register.

Preguntas frecuentes

¿Un número en rojo deja de enviar?

No automáticamente. El rojo indica riesgo. Lo que impide el envío es el estado del número (por ejemplo, restringido) o una restricción por política. Aun así, el rojo es el momento de pausar campañas e investigar.

¿Cuánto tarda la calidad en volver a verde?

Meta calcula la calificación sobre los últimos siete días, con más peso para los recientes. Sin nuevas señales negativas, tiende a mejorar a lo largo de esa ventana, pero no hay un plazo garantizado.

¿La calidad es del número o de la cuenta?

El color es del número de teléfono. El límite de mensajes, en cambio, es del portafolio comercial y depende de la calidad en todos los números y plantillas. Un número malo frena a todo el portafolio.

¿Una plantilla pausada se cobra o cuenta en el límite?

No. Según Meta, los intentos de envío de una plantilla pausada se rechazan, no se cobran y no cuentan en el límite de mensajes.

¿Los errores de entrega afectan la calidad?

La calificación viene de los comentarios de los usuarios (bloqueos, denuncias, silenciados, archivados). Fallos como el error 131049 no son comentarios negativos, pero reenviar una y otra vez a quien no interactúa suele generar bloqueos después. Consulta también los errores más comunes de la API.

---

Fuentes oficiales consultadas el 25/10/2026: Envío de mensajes y calidad, Límites de mensajes, Números de teléfono comerciales, Referencia de la Phone Number API, Calidad de plantillas, Pausa de plantillas, Throughput, Webhook message_template_quality_update, Webhook phone_number_quality_update, Aplicación de políticas, Sobre la calificación de calidad del número (Centro de ayuda), Política de mensajes de WhatsApp Business.