WhatsApp Cloud API con Embedded Signup de Meta

Visión general

La conexión guiada abre la autorización de Meta y vincula el número elegido a una bandeja de WhatsApp Cloud. Crear una bandeja requiere WhatsApp Embedded Signup Flow habilitado en la cuenta, tanto en instalaciones propias como en la nube. La instalación también necesita la aplicación de Meta configurada. Puede ejecutar el flujo un administrador o un perfil nativo autorizado con el alcance adecuado para gestionar la bandeja.

Requisitos previos

• Permiso para gestionar la bandeja dentro del alcance de acceso adecuado.
• Aplicación Meta configurada en la instalación y acceso a la empresa que administra el número.
• WhatsApp Embedded Signup Flow habilitado para crear una bandeja; WhatsApp Manual Transfer habilitado para la transferencia manual.
• Recuperar una bandeja existente utiliza el permiso para gestionarla.

Paso a paso

1. Abre Configuración → Bandejas de entrada → Añadir bandeja → WhatsApp.
2. Elige la conexión guiada con Meta e inicia sesión en la cuenta empresarial que administra el número.
3. Selecciona la WABA y el número correctos y completa los pasos solicitados por Meta.
4. Espera la confirmación de la configuración. Cerrar la ventana o recibir solo una parte de la autorización no completa la conexión.
5. Envía y recibe un mensaje de prueba con un contacto propio antes de iniciar la operación.

Configuración y opciones

Reconectar o reconfigurar una bandeja existente

Abre Configuración → Reconfigurar o usa el aviso de reconexión de la bandeja. La recuperación sigue disponible para el administrador autorizado aunque estén desactivadas la creación de nuevas bandejas o la antigua flag de reconfiguración. No crees otra bandeja para recuperar la conexión.

Selecciona el mismo número. La recuperación conserva la bandeja, conversaciones y la pareja WhatsApp Web del híbrido. Se rechaza un identificador que pertenezca a otro número. Coex utiliza este mismo flujo guiado.

Si aparece configuración pendiente, las credenciales se guardaron pero la plataforma aún no ha confirmado toda la configuración necesaria. La bandeja sigue disponible para reintentar la recuperación. No significa que la conexión esté terminada ni requiere crear otra bandeja. El mensaje indica la etapa pendiente — registro del número o entrega de mensajes (webhook) — y el reintento se hace desde el aviso de reconexión de la bandeja.

Interpretar el estado de la cuenta

Estado de la cuenta muestra lo que Meta informa hoy sobre el número. Arriba se indica cuándo Meta confirmó los datos por última vez (Verificado con Meta el). Verificar ahora vuelve a consultar a Meta; la plataforma lo hace como máximo una vez cada 30 segundos por bandeja, y el botón queda desactivado durante ese intervalo.

• Estado de envío: el estado que Meta calcula antes de cada mensaje, considerando el número, la cuenta de WhatsApp Business, el portafolio empresarial y la app: Disponible, Limitado o Bloqueado. Cuando algo limita o bloquea, la pestaña muestra el elemento afectado, la explicación de Meta y qué hacer, con las palabras de la propia Meta. Los avisos que Meta adjunta a un elemento también aparecen, incluso con el elemento disponible; el más grave es "la app no está suscrita al webhook de mensajes", que significa que el número no recibe los mensajes de los clientes. La línea Recibir llamadas por SIP muestra No configurado cuando el número no usa SIP, lo que es normal en la plataforma.
• Puntos de atención: avisos que la plataforma registra a partir de las notificaciones de Meta. Número reconectándose después de un cambio de dispositivo, conexión eliminada, autorización que debe renovarse, restricciones vigentes con su fecha de término, infracción de política, conversaciones con otro responsable en Conversation Routing, eventos de la cuenta o mensajes entregados en otra dirección y bandeja conectada hace más de 24 horas sin recibir ningún mensaje. Los avisos de conexión llevan a Ir a Configuración.
• Número: número, nombre visible y su estado, plataforma (solo Cloud API, o también la app WhatsApp Business), cuenta comercial oficial (insignia azul), modo de la cuenta (Producción o Prueba), estado del número y verificación por código.
• Capacidad y límites: velocidad de envío, límite de mensajes, calificación de calidad y, para quien puede ver costos, la estimación de mensajes de servicio gratuitos del mes. Mira la siguiente sección.
• Cuenta empresarial: cuenta de WhatsApp Business, portafolio, verificación de la empresa y revisión de la cuenta.
• Webhook: la dirección configurada y los campos de webhook suscritos en la app de Meta: la app de esta instalación en una bandeja creada con Embedded Signup, o tu propia app en una bandeja manual con App Secret. Si el campo messages no está suscrito, la app no recibe los mensajes de los clientes y la bandeja queda en silencio: la pestaña lo avisa primero. Sin App Secret, o cuando Meta rechaza el secreto, la lista se convierte en una lista de verificación para confirmar en el panel de apps de Meta. La pestaña también lista las apps suscritas a la cuenta de WhatsApp Business y avisa cuando más de una entrega los webhooks aquí. Si el callback de la app apunta a otro sistema, la pestaña lo avisa: Meta siempre entrega las actualizaciones de la cuenta, las alertas y el estado de las plantillas en el callback de la app, así que esta instalación deja de recibirlos.

Una información que Meta no devolvió no rompe la pestaña: el bloque afectado lo indica y conserva el último valor conocido. Un error al consultar la cuenta empresarial no elimina los datos válidos del número. El diagnóstico indica la etapa afectada y permite Intentar nuevamente.

Un error de objeto no disponible o permisos no demuestra por sí solo que el token haya caducado. Comprueba el número, la WABA, los permisos y la etapa indicada; usa Reconfigurar si necesitas renovar la autorización. La hora de consulta y el aviso de datos antiguos distinguen historial y estado actual.

Capacidad y límites del número

Velocidad de envío. Cuántos mensajes por segundo acepta Meta para este número, sumando los enviados y los recibidos. El ritmo sigue el límite del número en Meta: 80 mensajes por segundo al principio, hasta 1.000 si Meta lo amplía, y 20 en un número de coexistencia. Las campañas usan hasta el límite menos 5.

• Meta sube el número al nivel alto por sí sola cuando califica: límite de mensajes ilimitado, al menos 100.000 clientes únicos fuera de una ventana de atención en 24 horas y calidad Media o mejor. La plataforma lee el nivel cada 6 horas y lo actualiza al instante cuando Meta avisa del aumento.
• El bloque muestra Confirmada por Meta el con la fecha y la hora de la última confirmación.
• Cuando Meta todavía no confirmó el nivel, o la última confirmación tiene más de 24 horas, el bloque lo indica y usa el límite estándar de 80. La plataforma nunca supone el nivel alto sin esa confirmación.
• Nada se reserva para las respuestas: comparten el mismo margen que los demás envíos. Enviar por encima del límite hace que Meta rechace el mensaje.
• Una bandeja de WhatsApp Web no tiene este límite: sigue su propio control de ritmo contra bloqueos.

Límite de mensajes. Cuántos clientes distintos pueden recibir mensajes fuera de la ventana de atención en un período móvil de 24 horas. El límite es del portafolio empresarial y vale para todos sus números. La pestaña muestra una estimación del uso en las últimas 24 horas: clientes que recibieron una plantilla fuera de una ventana de atención abierta desde los números de esta cuenta conectados a ConversaLabs. Otras apps y cuentas del mismo portafolio no se cuentan; usa el valor como referencia, no como el número oficial de Meta. Cómo sube el límite, según Meta:

1. de 250 a 2.000 después de un camino: verificar la empresa, pedir la verificación a tu socio, o entregar 2.000 mensajes fuera de ventanas de atención a clientes únicos en 30 días, con plantillas de alta calidad;
2. después, Meta sube un nivel (10.000, 100.000, ilimitado) en hasta 6 horas cuando la calidad de los mensajes es alta y se usó al menos la mitad del límite actual en los últimos 7 días.

Calificación de calidad. Alta, Media, Baja o Sin calificación, según cómo los clientes recibieron los mensajes del número en los últimos días. Meta no informa la fecha de un cambio de calidad; la pestaña muestra el último cambio observado por la plataforma entre dos verificaciones.

Mensajes de servicio gratuitos. El bloque usa una franquicia mensual estimada de 1.000 mensajes de servicio por número. Franquicia mensual estimada; Meta no publica este límite en la documentación que seguimos. Muestra el uso y el saldo estimados a partir de las confirmaciones de entrega de Meta, que no confirman ese límite, y lleva a la pestaña Costos. Solo aparece para quien puede ver los costos de WhatsApp.

Cambiar a configuración manual

Debe estar habilitado WhatsApp Manual Transfer. Esta transición admite bandejas Cloud fuera de Coex: el servidor confirma con Meta que el número ya no usa Business App, verifica que los nuevos identificadores correspondan al mismo teléfono y rechaza una pareja híbrida existente. Los datos incompletos de estado no habilitan la operación.

1. Configura el webhook en tu app de Meta antes de migrar. Meta solo entrega los mensajes del número a través de una app que tenga un webhook de WhatsApp configurado; sin él, la migración se rechaza. En el App Dashboard de tu app, abre WhatsApp → Configuración (o Casos de uso → Personalizar → Configuración si la app se creó con el caso de uso de WhatsApp) y:

• en URL de callback, pega la URL que el asistente muestra para este número;
• en Token de verificación, pega el token de verificación de esta bandeja, que también muestra el asistente, y haz clic en Verificar y guardar;
• en Campos del webhook, suscribe messages (y calls si la bandeja recibe llamadas). Suscribe también los recomendados: account_update, smb_message_echoes, history, smb_app_state_sync, message_template_status_update, message_template_quality_update, template_category_update y user_preferences;
• mantén la app en modo En vivo: en modo Desarrollo, Meta no envía algunos webhooks.

2. Ejecuta el asistente. Abre Iniciar migración manual en el aviso de la bandeja y sigue los pasos: datos de la empresa (ID de la WABA y del número), token de acceso permanente de Usuario del sistema, Clave secreta de la app (opcional y recomendada), Webhook de tu app de Meta (copia la URL y el token y confirma que los configuraste) y revisión.

3. La plataforma lo verifica todo antes de guardar. Con el token ingresado, verifica con Meta la app dueña del token, que el token no venza, que tenga whatsapp_business_management y whatsapp_business_messaging para esta cuenta de WhatsApp Business y que la URL de callback de la app apunte a esta instalación — las actualizaciones de plantillas y las alertas de la cuenta siempre van a esa URL. Con la Clave secreta, verifica también que pertenezca a la app y que messages esté suscrito. Aun sin la Clave secreta, cuando Meta avisa que la app no está suscrita al webhook de mensajes, la migración se rechaza. Si falta algo, no se guarda nada y el mensaje indica qué configurar, con el nombre de la app.

Clave secreta de la app. Está en Configuración de la app → Básica. Con ella, la plataforma configura sola el webhook de WhatsApp de tu app durante la migración (URL de callback de esta instalación, token de verificación y campos del webhook, incluido messages), y el paso 1 queda solo como referencia. Si tu app ya envía sus webhooks a otro sistema, no se cambia nada: la migración se rechaza y el mensaje muestra la dirección actual. Con ella, también se verifica la firma de cada webhook de tu app; sin ella, los webhooks de la app se aceptan sin esa verificación y la pestaña Estado de la cuenta lo advierte. Después de guardarla, no se vuelve a mostrar.

Transferencia pendiente. Si Meta rechaza la configuración después de guardar las credenciales, la bandeja muestra el aviso Transferencia manual pendiente con la causa. Cuando Meta la rechaza porque la app no tiene un webhook suscrito a messages, el aviso nombra la app y muestra la URL que se debe configurar. Corrígelo en el App Dashboard y usa Reintentar transferencia, ingresando el token otra vez. Con el registro automático de webhook activo, el reintento rehace la configuración aunque Meta no responda la verificación previa. Si la plataforma no puede consultar a Meta en ese momento, no se cambia nada y el mensaje pide intentarlo de nuevo en unos minutos.

4. Quita la app anterior. Después de la migración, la app de la instalación sigue suscrita a la cuenta de WhatsApp Business y entrega los mismos webhooks que tu app, así que llegan duplicados. En Estado de la cuenta → Webhook, la plataforma lista las apps suscritas y muestra la acción Quitar la app. Antes de quitarla, verifica con Meta que tu app esté suscrita y entregue aquí este número, que ninguna otra bandeja de la misma cuenta dependa de la app anterior y que la entrega esté comprobada: un webhook firmado con tu Clave secreta llegó después de la migración o, sin Clave secreta, confirmas que un mensaje de prueba llegó a la bandeja. Meta deja de entregar a la app anterior de inmediato; puedes deshacer la eliminación durante 72 horas. Cuando la plataforma ya no pueda quitar la app por ti, el aviso pide quitarla de la cuenta de WhatsApp Business en las herramientas de Meta.

Para recuperar Coex o una bandeja híbrida, usa Reconfigurar. La transferencia manual no elimina la pareja ni sustituye silenciosamente el número atendido.

Número que otro socio ya usa

En el modelo de cuentas de Meta vigente desde septiembre de 2026, ya no existe la migración de números entre socios. Para traer a la plataforma un número que hoy atiende otro socio de WhatsApp:

1. El cliente comparte con la plataforma la cuenta de WhatsApp dueña del número, en este Embedded Signup (eligiendo ese número) o en Meta Business Suite. El número no cambia de lugar y las conversaciones continúan.
2. El socio anterior sigue en el número hasta que el cliente lo quite en Meta Business Suite.
3. Con dos socios en el número, Meta enruta cada conversación a un único responsable. Pide al cliente que abra Conversation Routing en Meta Business Suite y defina la plataforma como responsable principal de las entradas que atenderá el equipo (por ejemplo, Atención al cliente).
4. Hasta entonces, la nueva bandeja puede no recibir mensajes, aunque la conexión esté completa.

La primera pantalla de Meta pide el número antes de cualquier otra elección. Si el número ya se usa en la app WhatsApp Business, Meta abre sola el flujo de coexistencia.

Casos de uso

• Conectar un número Cloud a la plataforma por primera vez.
• Renovar la autorización Cloud o Coex conservando conversaciones e historial.
• Migrar una bandeja Cloud elegible a una aplicación Meta gestionada manualmente.

Consejos, límites y buenas prácticas

• Confirma el número y la WABA antes de completar la autorización.
• Conserva la bandeja existente durante la recuperación; crear otra puede separar su historial.
• Prueba envío y recepción con un contacto propio después de configurar o recuperar. Un aviso de configuración pendiente requiere completar la etapa indicada.

Solución de problemas

• Ventana cancelada o caducada: inicia el flujo de nuevo en la misma bandeja.
• Falta la opción de creación: comprueba el recurso y la configuración de la aplicación Meta.
• No puedes recuperar una bandeja: comprueba el permiso para gestionarla y su alcance.
• Configuración pendiente: reintenta la recuperación, confirma el webhook y prueba una recepción real.
• La migración se rechazó porque la app no tiene webhook: configura la URL de callback, el token de verificación y el campo messages en el App Dashboard de la app indicada y vuelve a intentarlo. No se guardó nada.
• La Clave secreta se rechazó: cópiala de Configuración de la app → Básica de la misma app del token, o deja el campo vacío.
• Los mensajes y eventos llegan duplicados después de la migración: la app anterior sigue suscrita. Quítala en Estado de la cuenta → Webhook.
• Número diferente: selecciona el número ya vinculado; la recuperación no permite sustituirlo.
• La bandeja se conectó, pero no recibe mensajes: probablemente el número todavía tiene otro socio como responsable principal. Pide al cliente que ajuste el Conversation Routing en Meta Business Suite.
• Estado de envío Limitado o Bloqueado: sigue Qué hacer en el elemento indicado. Los textos vienen de Meta; después de corregirlo en WhatsApp Manager, usa Verificar ahora.
• Velocidad de envío Sin confirmar: Meta no confirmó el nivel en las últimas 24 horas. Usa Verificar ahora; mientras tanto rige el límite estándar de 80 mensajes por segundo.

Ver también

• Enrutamiento de conversaciones de WhatsApp: Agente de Meta y otros socios
• Coexistence de WhatsApp Cloud
• Bandeja híbrida de WhatsApp