API oficial

WABA y portafolio: la estructura de Meta que decide si tu envío se realizará

Por VeyloCRM · · 14 min de lectura

Casi todo problema extraño en la API oficial — plantilla que existe pero no se encuentra, imagen que funciona en un número y falla en otro, cola que se bloquea con todo en verde — tiene la misma causa: una confusión entre las capas de la estructura de Meta. Son tres, cada una guarda cosas diferentes, y lo que pertenece a una no se transfiere a la otra. Entender este diseño es lo que separa una operación predecible de una serie de sorpresas en medio del envío.

Las tres capas

La estructura de Meta para mensajes empresariales tiene tres niveles encajados, y cada uno responde por cosas diferentes:

La regla que explica casi todos los problemas: cada cosa pertenece a una capa específica y no se hereda a las otras. La plantilla pertenece a la cuenta comercial. La calidad pertenece al número. El pago pertenece al portafolio. Quien trata las tres como si fueran "la cuenta de WhatsApp de la empresa" acaba sorprendido.

Portafolio: donde reside la empresa

El portafolio es lo que Meta entiende como la organización. En él están:

Este último punto merece atención porque es el más pesado: una restricción aplicada al portafolio alcanza todo lo que está dentro de él. No sirve cambiar de número ni crear otra cuenta comercial dentro de él — el bloqueo es de la capa superior.

La cuenta comercial de WhatsApp

La cuenta comercial es la capa de trabajo del día a día. Es la que guarda:

La frase que vale memorizar es esta: la plantilla es aprobada por cuenta comercial. Un modelo creado en la cuenta A no existe para un número que está en la cuenta B. Es la explicación más común para "la plantilla estaba aprobada y aun así el envío falló".

Lectura liberada

Continúa leyendo gratis

Completa una vez y libera este y todos los demás artículos del blog. No cobramos nada — solo queremos saber para quién estamos escribiendo.

Toma 20 segundos. ¿Prefieres hablar directo por WhatsApp?

El número y lo que le pertenece

El número es la capa más concreta y la que el cliente ve. Le pertenecen:

  • El nombre de exhibición, que pasa por aprobación y debe corresponder a la empresa.
  • La foto y el perfil comercial.
  • La clasificación de calidad, calculada a partir de bloqueos y denuncias.
  • El límite de conversaciones iniciadas, que aumenta con volumen y calidad.
  • El identificador técnico, usado en cada llamada de envío.

Este identificador guarda una trampa silenciosa: cambia cuando el número es desconectado y conectado de nuevo. Sistemas que archivan conversaciones por este identificador en lugar del teléfono terminan con el historial huérfano después de una reconexión — las conversaciones siguen en la base, pero nadie las encuentra. Quien construye integración debe casar historial por teléfono, nunca por identificador de conexión.

Lo que no se transfiere de una cuenta a otra

La lista de cosas que quedan atadas a la cuenta comercial explica la mayoría de los incidentes:

  • Plantillas. Deben ser sometidas y aprobadas en cada cuenta que las va a usar.
  • Archivos enviados a la plataforma. El identificador de una imagen pertenece al número que la envió; reutilizarlo en otro número falla.
  • Límite y calidad. Un número maduro no presta reputación a un número nuevo de la misma cuenta.
  • La ventana de atención. Es entre el cliente y un número específico. Responder por otro número no usa la ventana abierta por el primero.

Por eso el rodaje de números requiere preparación. Distribuir el envío entre tres números solo funciona si los tres tienen la plantilla aprobada, el medio enviado y cuota disponible. Si falta cualquiera de estos en uno de ellos, la cola se detiene cuando llega su turno — y el síntoma es una falla masiva en medio del envío, que parece bloqueo y no lo es.

¿Una cuenta o varias?

La pregunta aparece tan pronto la empresa pasa de un número. La respuesta depende de tres criterios.

Junta en la misma cuenta cuando los números pertenecen a la misma marca, usan las mismas plantillas y atienden al mismo público. Una cuenta solo significa una biblioteca de plantillas para mantener, una suscripción a eventos y menos configuración duplicada.

Separa en cuentas diferentes cuando existen marcas distintas con nombres de exhibición propios, cuando el contenido es muy diferente — una operación de cobranza y una de ventas no deberían compartir reputación —, o cuando cada unidad necesita facturación y responsables propios.

Un cuidado sobre el aislamiento: separar cuentas no protege contra todo. Restricción a nivel de portafolio alcanza todas las cuentas dentro de él. La separación aísla plantilla, límite y buena parte de las restricciones operativas — no la integridad de la organización.

Cobro: la falla más silenciosa

Este es el problema que más consume horas de investigación técnica sin ser técnico.

Cada cuenta comercial necesita un medio de pago válido asociado. Cuando hay factura pendiente, los envíos pueden ser bloqueados incluso con el número en calidad verde, plantilla aprobada y cuota disponible. Y la falla devuelta no dice "hay una factura pendiente" — viene genérica.

El escenario clásico es una empresa con varios números distribuidos en cuentas comerciales diferentes: una de ellas tiene pendiente y las otras no. El envío funciona normalmente hasta que el rodaje llega a ese número, y ahí se bloquea. Desde afuera, parece un defecto intermitente del sistema.

La conclusión práctica: antes de investigar código, verifica la situación financiera de cada cuenta comercial. Es una verificación de dos minutos que ahorra un día.

Verificación de la empresa y lo que libera

La verificación ocurre en el portafolio y es Meta revisando documentos para confirmar que la organización existe y que quien la administra tiene relación con ella. Suele exigir documento de constitución, comprobante de domicilio y alguna forma de presencia pública verificable.

Sin verificación, la operación funciona en modo limitado: menos números permitidos, techo de conversaciones más bajo y restricciones en algunos recursos. Con verificación, los límites se abren conforme al uso.

Dos puntos que ahorran retrabajo. Primero: el nombre de exhibición del número debe tener relación clara con la empresa verificada — nombre de fantasía sin vínculo es la causa más común de rechazo en esta etapa. Segundo: la verificación es del portafolio, por lo que vale para todas las cuentas comerciales dentro de él, lo que es un buen argumento para no dispersar operaciones por portafolios diferentes sin necesidad.

Conectar el número de un cliente

Para quien presta servicio, existe un protocolo que evita descubrir problemas el día del envío:

  • El número debe estar libre. Un teléfono ya conectado a la aplicación común debe ser desvinculado antes, y esta migración borra el historial local del dispositivo — el cliente debe saberlo antes, no después.
  • El portafolio es del cliente. La empresa que presta servicio recibe acceso; no debe ser dueña de los activos del cliente. Esto evita disputas posteriores y protege a ambas partes.
  • Verificación antes del volumen. Comenzar el proceso temprano, porque no es instantáneo.
  • Plantillas aprobadas antes de la campaña. El análisis lleva tiempo y la primera presentación suele necesitar ajustes.
  • Medio de pago configurado y probado con un envío real, no solo registrado.
  • Calentamiento. Número nuevo tiene límite bajo. Subir volumen gradualmente es lo que construye calidad en lugar de quemarla en la primera semana.

Quién puede hacer qué

El permiso es la parte de la estructura que más genera bloqueos inexplicables, porque el error devuelto rara vez dice "falta permiso para esta persona".

Los roles se distribuyen por capa. En el portafolio existen administradores, que manejan todo, incluyendo pago y verificación, y empleados, con acceso solo a los activos que se les conceden. En cada activo — la cuenta comercial de WhatsApp, una Página, una cuenta de Instagram — el permiso se asigna por separado, y tener acceso al portafolio no significa tener acceso a todo lo que está dentro.

Tres situaciones concentran los problemas:

  • La persona que creó todo salió de la empresa. Si era el único administrador del portafolio, la organización pierde el control de sus propios activos, y recuperarlo es un proceso largo con Meta. La regla es tener siempre al menos dos administradores, y que al menos uno sea un cargo estable.
  • El sistema integrado no tiene permiso sobre ese activo. La empresa concede acceso al portafolio y olvida concederlo al número, y el envío falla con error genérico de permiso.
  • Aplicación en modo restringido. Mientras una integración no tiene aprobación plena, funciona solo para personas con rol formal en la aplicación. Esto hace que una prueba pase con el equipo y falle con el primer cliente real — y no es un defecto, es la etapa de autorización.

Vale registrar en algún lugar accesible quién es administrador de cada capa. Parece burocracia hasta el día en que alguien sale y nadie puede aprobar una plantilla.

Una operación en números

Una empresa con tres números sirve de ejemplo de lo que cuesta la estructura cuando se monta sin plan.

Montaje improvisado: cada número fue conectado por una persona diferente, en tres cuentas comerciales separadas, dentro de dos portafolios. La plantilla de campaña fue aprobada en una sola cuenta. El envío de 9.000 contactos se distribuyó igualmente entre los tres números.

  • 3.000 mensajes salieron por el número A, que tenía la plantilla — 96% de entrega
  • 3.000 fallaron en el número B por plantilla inexistente en esa cuenta
  • 3.000 fallaron en el número C por el mismo motivo, más una factura pendiente en ese portafolio

Resultado: 33% del envío entregado, dos números con historial de falla masiva y un equipo convencido de que el problema era el sistema de envío. El costo real no fueron los 6.000 mensajes perdidos — fue el día de investigación sobre un problema que estaba enteramente en el panel de Meta.

La misma operación con estructura planificada — un portafolio, una cuenta comercial, los tres números dentro de ella, plantilla aprobada una vez y válida para los tres, pago único — entrega los mismos 9.000 sin intervención. La diferencia entre los dos escenarios no es técnica ni cuesta dinero: es una hora de organización antes de comenzar.

Cinco errores de estructura

  • Asumir que plantilla aprobada vale para todos los números. Vale para la cuenta comercial en que fue aprobada, y el rodaje choca con esto en medio del envío.
  • Dispersar números por cuentas y portafolios sin necesidad. Multiplica biblioteca de plantillas, verificación y facturas — y ningún beneficio.
  • Ser dueño del portafolio del cliente. Crea disputa de propiedad y responsabilidad sobre activos que no son tuyos.
  • Buscar defecto técnico antes de revisar la factura. Pendencia financiera bloquea envío con todo en verde y devuelve error genérico.
  • Guardar historial por identificador de conexión. Reconectar el número genera identificador nuevo y deja huérfanas las conversaciones; el vínculo correcto es el teléfono.

Los números para monitorear

Cinco indicadores mantienen la estructura bajo control. La cobertura de plantillas por número — cuántos de los modelos que la operación usa existen en cada número —, que debería ser 100% antes de cualquier envío con rodaje. El estado de verificación del portafolio, que desbloquea límites y suele recordarse demasiado tarde. La situación financiera de cada cuenta comercial, revisada antes de campaña grande. La calidad y el límite por número, monitoreados individualmente, porque el promedio oculta el número que está a punto de ser restringido. Y la cantidad de cuentas comerciales activas, que debería ser el menor número que atiende la operación — cada cuenta adicional es una biblioteca de plantillas, una configuración de eventos y una factura para que alguien olvide.

Preguntas frecuentes

¿Cuál es la diferencia entre portafolio, cuenta comercial y número en Meta?

Son tres capas encajadas, y cada una guarda cosas diferentes que no se heredan a las otras. El portafolio comercial es la capa más alta y representa a la organización: en él están personas y permisos, la verificación de la empresa, el medio de pago, los activos como páginas y cuentas de Instagram, y el historial de integridad — una restricción aplicada aquí alcanza todo lo que está dentro. La cuenta comercial de WhatsApp, o WABA, está dentro del portafolio y es la capa de trabajo: guarda las plantillas, agrupa los números y concentra la suscripción a eventos. El número de teléfono está dentro de la cuenta comercial y es suyo el nombre de exhibición, la foto, la clasificación de calidad y el límite de conversaciones iniciadas. La regla que explica casi todos los problemas es que cada cosa pertenece a una capa específica: la plantilla es de la cuenta, la calidad es del número, el pago es del portafolio.

¿Por qué mi plantilla aprobada no funciona en otro número?

Porque la plantilla es aprobada por cuenta comercial, no por empresa ni por número. Un modelo creado en la cuenta A simplemente no existe para un número que está en la cuenta B, y esta es de lejos la explicación más común para "la plantilla estaba aprobada y aun así el envío falló". Lo mismo vale para archivos: el identificador de una imagen enviada a la plataforma pertenece al número que la envió, y reutilizarlo en otro número falla. Límite y calidad tampoco se transfieren — un número maduro no presta reputación a un número nuevo de la misma cuenta. Y la ventana de atención es entre el cliente y un número específico, por lo que responder por otro número no aprovecha la ventana abierta por el primero. Por eso el rodaje de números requiere preparación: los tres deben tener la plantilla aprobada, el medio enviado y cuota disponible, o la cola se detiene cuando llega el turno del que falta.

¿Debo usar una sola cuenta comercial o varias?

Junta en la misma cuenta cuando los números pertenecen a la misma marca, usan las mismas plantillas y atienden al mismo público — una cuenta solo significa una biblioteca de plantillas para mantener, una suscripción a eventos y menos configuración duplicada. Separa en cuentas diferentes cuando existen marcas distintas con nombres de exhibición propios, cuando el contenido es muy diferente, ya que una operación de cobranza y una de ventas no deberían compartir reputación, o cuando cada unidad necesita facturación y responsables propios. Un cuidado importante sobre el aislamiento: separar cuentas no protege contra todo. Restricción a nivel de portafolio alcanza todas las cuentas dentro de él. La separación aísla plantilla, límite y buena parte de las restricciones operativas, pero no la integridad de la organización.

El envío se bloquea con el número en verde y la plantilla aprobada. ¿Por qué?

La causa más frecuente y silenciosa es financiera. Cada cuenta comercial necesita un medio de pago válido asociado, y cuando hay factura pendiente los envíos pueden ser bloqueados incluso con calidad verde, plantilla aprobada y cuota disponible — y la falla devuelta no dice "hay una factura pendiente", viene genérica. El escenario clásico es una empresa con varios números distribuidos en cuentas comerciales diferentes, una con pendiente y las otras no: el envío funciona normalmente hasta que el rodaje llega a ese número y entonces se bloquea, lo que desde afuera parece un defecto intermitente del sistema. La conclusión práctica es directa: antes de investigar código, verifica la situación financiera de cada cuenta comercial. Es una revisión de dos minutos que ahorra un día entero.

¿Qué revisar antes de conectar el número de un cliente?

Seis puntos evitan descubrir problemas el día del envío. El número debe estar libre — teléfono ya conectado a la aplicación común debe ser desvinculado, y esta migración borra el historial local del dispositivo, algo que el cliente debe saber antes y no después. El portafolio debe ser del cliente, con la empresa prestadora recibiendo acceso en lugar de ser dueña de los activos, lo que evita disputas y protege a ambas partes. La verificación de la empresa debe comenzar temprano, porque no es instantánea y es la que desbloquea límites. Las plantillas deben estar aprobadas antes de la campaña, ya que el análisis lleva tiempo y la primera presentación suele necesitar ajustes. El medio de pago debe estar configurado y probado con un envío real, no solo registrado. Y el número nuevo necesita calentamiento: comenzar con volumen bajo y subir gradualmente es lo que construye calidad en lugar de quemarla en la primera semana.

Estructura organizada es envío que no se bloquea a mitad

VeyloCRM muestra qué plantillas existen en cada número antes de que el envío comience, avisa cuando un número no tiene el modelo elegido en lugar de fallar en medio de la cola, casa el historial de conversaciones por teléfono y no por identificador de conexión, y mantiene WhatsApp, Instagram y Messenger en el mismo panel — con toda la operación en un solo lugar.