Incorporación de números de WhatsApp (Meta Cloud API)

¿Qué hace Incorporación de números de WhatsApp (Meta Cloud API)?

Conectar un número parecen 10 clics. En la práctica, falla por el orden de los pasos, por qué portafolio posee qué, y por pantallas de Meta que dicen "conectado" cuando no se entrega nada. Esta habilidad es el orden seguro más los bloqueos que realmente han ocurrido, con sus soluciones.

Etiquetas de confianza utilizadas a continuación: [oficial] = indicado en developers.facebook.com (URL en la tabla); [campo] = ocurrió en incorporaciones reales y la solución se confirmó en vivo; [no confirmado] = visto, causa o solución nunca comprobada. Nunca presentes [campo] o [no confirmado] como política de Meta.

Palabras: nunca mezcles estas cuatro

• Portafolio empresarial (Business Manager): la empresa en Meta.
• Cuenta comercial de WhatsApp (WABA): vive dentro de un portafolio. En la interfaz de usuario, usa el ID de la Cuenta de mensajería, no el ID de "Cuenta/presencia de WhatsApp" (este último devuelve "This API is not supported") [campo].
• Número de teléfono: vive dentro de una WABA. Su ID de número de teléfono no es el número de teléfono.
• Aplicación de Meta: vive en una cuenta de desarrollador y está vinculada a un portafolio; contiene el token, el secreto de la aplicación y el webhook.

Cuando indiques un límite, di a cuál de las cuatro se refiere.

Límites que determinan el plan [oficial]

• Un portafolio nuevo puede registrar 2 números de teléfono; el límite aumenta a 20 cuando la empresa está verificada o alcanza el límite de mensajería de 2000.
• Los límites de mensajería son por portafolio, compartidos por todos sus números: 250 → 2000 → 10 000 → 100 000 → ilimitado. Un número ocupado puede agotar el saldo de todos.
• Registrar y desregistrar: 10 solicitudes por número cada 72 h cada una; pasado eso, el error 133016 bloquea el número durante 72 h. No presiones "Activar" mientras depures.
• Agregar un número en WhatsApp Manager o el panel de la aplicación no lo registra para Cloud API; aún se necesita la llamada de registro.
• Un número ya utilizado con WhatsApp (aplicación de teléfono) no se puede registrar hasta que se elimine esa cuenta.
• Eliminar un número: solo administradores del portafolio, no mediante API, necesita el PIN de 2 pasos si está conectado, y es imposible si envió mensajes de pago en los últimos 30 días. Trata la eliminación como irreversible.

Antes de comenzar (recopilar una vez)

Nombre de la empresa exactamente como lo verán los clientes, nombre legal, país, dirección completa, teléfono, sitio web o página de Facebook, correo electrónico, logotipo y el número a conectar. El número no debe tener WhatsApp instalado (si lo tiene, elimina primero la cuenta de WhatsApp en ese teléfono). Decide quién inventa y guarda el PIN de 6 dígitos.

Orden seguro (cada paso termina con una verificación de lectura)

1. Portafolio (business.facebook.com): completa la Información comercial por completo (nombre legal, dirección, teléfono, sitio web) antes de agregar un número. Si está vacío, la incorporación falló con "tu empresa no cumple con la política de WhatsApp" (#2494070) [campo].
2. Cuenta de WhatsApp + número (Configuración del portafolio → Cuentas → Cuentas de WhatsApp → Agregar → número nuevo). Nombre para mostrar = el nombre comercial del cliente, nunca el de la agencia. Verifica por SMS o VOZ para líneas fijas [oficial]. Verificación de lectura: el número aparece debajo de la WABA.
3. Aplicación de Meta (developers.facebook.com → Crear aplicación → Caso de uso de WhatsApp), vinculada al mismo portafolio que posee la WABA. Aplicación en un portafolio y WABA en otro: todo se mostraba en verde y no se entregaba ningún mensaje; mover la aplicación al portafolio de la WABA lo solucionó [campo]. Configuración → Básico: URL de privacidad/términos/eliminación de datos que devuelvan 200, categoría, icono.
4. Usuario del sistema en ese portafolio que tenga la aplicación y la WABA como activos; token con whatsapp_business_messaging + whatsapp_business_management, sin caducidad. Un humano pega el token donde se almacena; nunca lo muestres.
5. IDs, leídos por ti, no escritos por una persona: GET /{id-waba}/phone_numbers → ID del número de teléfono. Almacenar el número de teléfono en la variable ID del número de teléfono rompió un bot [campo].
6. Variables de entorno en el proyecto de alojamiento exacto. Varios proyectos de clientes con los mismos nombres de variables: di el nombre del proyecto y verifica el título antes de guardar. Los ID de un cliente se colaron en el proyecto de otro y su bot en vivo apuntaba al número equivocado [campo].
7. Webhook (Aplicación → WhatsApp → Configuración): https://<dominio>/webhook más token de verificación; suscríbete al campo messages (no siempre está activado). Luego suscribe la WABA a la aplicación: POST /{id-waba}/subscribed_apps.
8. Registra el número: POST /{id-número-teléfono}/register con el PIN de 6 dígitos. Si el número ya tiene verificación en 2 pasos, usa el PIN existente [oficial]. Verificación de lectura: GET /{id-número-teléfono}?fields=status,platform_type,name_status → CONNECTED y CLOUD_API. Antes de esto muestra PENDING / NOT_APPLICABLE [campo].
9. Publica la aplicación, luego envía "Hola" desde un teléfono personal y mira la respuesta del bot.
10. Facturación: método de pago, zona horaria y moneda configurados en la cuenta de WhatsApp antes de enviar plantillas (de lo contrario, 131042) [oficial].
11. Verificación de lectura final: estado del número, GET /{id-waba}/subscribed_apps muestra solo esta aplicación, URL del webhook y campos, debug_token muestra la aplicación correcta y un token de usuario del sistema.

El nombre para mostrar puede permanecer "en revisión" durante días mientras el número ya funciona [campo]; no hagas clic en Editar, porque editar reinicia la revisión.

Reglas de oro

• Mismo portafolio para la aplicación y la WABA. Si el portafolio del cliente está atascado en revisión, una salida probada en el campo es poner el número en una WABA en un portafolio que funcione (el tuyo), con la aplicación en ese mismo portafolio, dentro del límite de 2 números [campo]. El camino oficial a largo plazo es convertirse en un Proveedor de tecnología con registro integrado.
• Una aplicación por cliente, por defecto. La URL de callback de la aplicación es el destino predeterminado. Meta admite anulaciones de webhook por WABA y por número [oficial], pero si no las has probado, mantén una aplicación por cliente.
• Cuando el dominio de alojamiento cambie, actualiza el webhook en Meta en ese momento y verifícalo. Un cambio de dominio detuvo silenciosamente un bot [campo].
• Nunca uses la ruta "Continuar" que instala la aplicación WhatsApp Business en el teléfono para un número que debe permanecer en Cloud API: saca el número de la API [campo].
• Prueba primero lo que no rompe nada. Desregistrar, eliminar o mover un número son el último recurso, solo si Meta lo requiere (consulta los límites anteriores).
• Una verificación de estado es verde solo cuando Meta lo dice: lee el estado del teléfono desde Meta. Un token válido no prueba nada sobre el número [campo].
• Una redirección a la URL de un portafolio no prueba quién posee un activo. Confirma el nombre del portafolio en pantalla [campo].

Solución de problemas

Síntoma	Causa	Solución	Etiqueta / fuente
Todo verde, no llega nada	Aplicación y WABA en diferentes portafolios	Nueva aplicación en el portafolio de la WABA; eliminar el webhook de la aplicación antigua	[campo]
Los mensajes llegan dos veces / advertencias de "app secret mismatch"	Dos aplicaciones suscritas a la misma WABA	Eliminar el webhook y la suscripción de la aplicación antigua	[campo]
El bot se detuvo después de un despliegue	Webhook aún en el dominio antiguo	Actualizar el webhook y verificar su lectura	[campo]
"No se pudo asignar el socio" al compartir la WABA del cliente	Nunca comprobado (portafolio nuevo o no verificado, cuenta en revisión)	Evitar compartir: construir en un solo portafolio (ver las reglas de oro)	[no confirmado] causa, [campo] solución alternativa
"Business doesn't meet WhatsApp policy" (#2494070) durante la incorporación del desarrollador	Información comercial incompleta / portafolio nuevo	Completar la información comercial; agregar el número desde WhatsApp Manager en su lugar	[campo]
"This API is not supported" con el ID de WABA	Se usó el ID de "Cuenta de WhatsApp"	Usar el ID de la Cuenta de mensajería	[campo]
Estado PENDING, plataforma NOT_APPLICABLE	Agregado pero no registrado	POST /register con PIN	[oficial] + [campo]
133005	PIN de 2 pasos incorrecto	Usar el PIN existente del número	códigos de error
133006	Número no verificado	Verificar por SMS/VOZ, luego registrar	códigos de error
133008 / 133009	Demasiados o demasiado rápidos intentos de PIN	Esperar el tiempo indicado en details	códigos de error
133010	Número no registrado en la plataforma	Registrarlo	códigos de error
133015	Número recién eliminado, aún eliminándose	Esperar 5 minutos	códigos de error
133016	Más de 10 solicitudes de registro/desregistro en 72 h	Detenerse; esperar a que termine el bloqueo	registro
133000	Un desregistro anterior falló	Desregistrar de nuevo, luego registrar	códigos de error
"Number already has WhatsApp"	Número aún en la aplicación de teléfono u otra cuenta	Eliminar primero esa cuenta de WhatsApp	números de teléfono
131042 en plantillas	Método de pago: línea de crédito, zona horaria o moneda no configurados, cuenta suspendida	Arreglar la facturación en WhatsApp Manager; mostrar al usuario el texto error_data.details de Meta, no una suposición	códigos de error
131042 solo en unos pocos destinatarios	Según el texto de Meta es de toda la cuenta, pero en una verificación en vivo 16 de 18 plantillas se entregaron	Contar los entregados vs fallidos en el mismo período antes de llamarlo de toda la cuenta o pausar algo	[campo] heurística
131049	No entregado "para mantener un ecosistema saludable"	Esperar al menos 24 h antes de reenviar	códigos de error
131026	El destinatario no puede recibir (sin WhatsApp, versión antigua, términos)	Contactarlo por otro medio	códigos de error
131031	WABA restringida por violación de política	Consultar Aplicación de políticas y la API de estado de salud	códigos de error
No se puede vincular el número a la página de Facebook para anuncios de click-to-WhatsApp	Nombre para mostrar aún en revisión (probablemente)	Esperar la aprobación, luego Página → Cuentas vinculadas → WhatsApp	[no confirmado]

Otras páginas oficiales: comenzar · límites de mensajería · anulaciones de webhook.

No verificado (dilo si surge)

• Qué requiere realmente "No se pudo asignar el socio".
• Si un portafolio nuevo y no verificado puede crear una WABA.
• Mover un número entre WABAs: la guía de Meta dice que no es compatible para cuentas en el nuevo modelo de cuenta; nunca se completó en el campo.
• Tiempos oficiales de revisión del nombre para mostrar. Las dos URL oficiales devolvieron 404 en noviembre de 2026.

Quién hace qué

El agente realiza todas las comprobaciones de pantalla y API que pueda. La persona solo proporciona lo que una máquina no puede: el código SMS/voz del teléfono, el PIN, pegar secretos, verificaciones de identidad, pagos.