Coexistencia en WhatsApp: la app Business y la Cloud API en el mismo número

Qué es la coexistencia, y por qué importa a quien ya atiende desde la app

La página Onboarding WhatsApp Business app users de la documentación de la Cloud API describe un flujo en el que una empresa que ya usa la app WhatsApp Business conecta el mismo número a la plataforma de Meta, a través de un socio, y empieza a usar las dos cosas a la vez. La propia página indica que a veces se llama “Coexistence” en los canales de soporte y en la documentación de socios. Salió el 11 de febrero de 2025, según el changelog.

Para la pequeña y mediana empresa, es la respuesta a la duda que más aparece cuando se habla de la API: ¿tengo que renunciar a la app? Con la coexistencia, no. El dueño sigue respondiendo desde el móvil, con las etiquetas, el catálogo y las respuestas rápidas de siempre, y la misma conversación pasa a existir también en un inbox con varios agentes, en automatizaciones, campañas con plantillas e integraciones con el resto del sistema.

La alternativa es la migración completa, y Meta es clara sobre su coste. Para llevar un número de la app a la Cloud API sin coexistencia hay que borrar la cuenta de la app y, según la página que describe esa migración, el historial existente se pierde y el número no se puede volver a usar en la app hasta que se dé de baja de la Cloud API. Con la coexistencia, el historial se conserva. Por eso, para quien tiene años de conversaciones en el móvil, la coexistencia suele ser el primer paso — y a veces el único.

Sobre disponibilidad, una salvedad honesta: la página actual no publica lista de países. El changelog registra la apertura gradual de mercados — India, Australia, Japón, la Unión Europea, el Reino Unido y, en 2026, Nigeria y Sudáfrica —, de modo que España, como el resto de la UE, está disponible desde octubre de 2025. El error 3441042, de función no disponible para números de la región, sigue existiendo, lo que indica que todavía hay alguna restricción geográfica en algún lugar.

Requisitos y el camino de la incorporación

Los requisitos oficiales son pocos. La app WhatsApp Business tiene que estar en la versión 2.24.17 o posterior. La conexión se hace a través de un socio de Meta — Solution Partner o Tech Provider — mediante el Embedded Signup, el flujo de alta integrado en la web del socio. En la configuración documentada, el socio pasa whatsapp_business_app_onboarding como featureType; en las versiones más recientes del flujo, Meta también desvía a la coexistencia automáticamente cuando detecta que el número introducido ya está en la app.

Para el dueño, el camino es corto: introduce el número, recibe en la propia app un mensaje de la cuenta oficial de Facebook Business, pulsa para conectar, elige si quiere compartir el historial de conversaciones y confirma — en una variante del flujo, escaneando un código QR desde dentro de la app. El registro del número en la Cloud API, que en la incorporación normal es un paso aparte, se omite: el número ya está registrado. Al final, el socio recibe el evento FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING y puede comprobar los campos is_on_biz_app y platform_type del número.

Los errores del camino dicen más que la lista de requisitos. El 3441045, con el mensaje de que hace falta más actividad en la app, aparece en números nuevos o poco usados — Meta no publica cuántos días de uso bastan. El 2655093 avisa de que cambiar de socio no está soportado en este flujo y pide desconectar el socio actual desde la propia app. Y, después de una desconexión, la página de errores pide esperar 15 minutos antes de volver a intentarlo.

Las 24 horas que no vuelven: contactos e historial

Terminada la incorporación, empieza el reloj que más importa. Según la página de la coexistencia, el socio tiene 24 horas para sincronizar los contactos y el historial de conversaciones del cliente; pasado el plazo, hay que desconectar al cliente y repetir el flujo entero. Y la sincronización solo se puede hacer una vez — para repetirla, el mismo camino: desconectar y empezar de nuevo.

La petición se hace con POST /<PHONE_NUMBER_ID>/smb_app_data, con sync_type igual a smb_app_state_sync para los contactos o history para las conversaciones. La respuesta solo confirma la petición, con un request_id; los datos llegan después, por webhooks. En nuestra implementación, el orden es primero contactos y después historial, para que las conversaciones encuentren a quién vincularse cuando lleguen. Meta pide que el dueño mantenga la app abierta durante la sincronización, que puede tardar varios minutos.

Lo que llega tiene límites claros. Conversaciones individuales de los últimos seis meses — 180 días contados desde la incorporación. Los grupos no se sincronizan. Los archivos multimedia solo llegan con el archivo si se enviaron en los 14 días anteriores a la incorporación; el resto llega como marcador, sin forma de recuperarlo después. Los contactos llegan todos los que tienen número de WhatsApp. Si el dueño rechazó compartir el historial, el webhook history llega con el error 2593109, y no hay nada que importar.

Al ser una única oportunidad, la sincronización no admite fallos silenciosos. Nuestro parser se escribió a partir de la documentación, y el peor desenlace posible sería recibir el historial, no reconocer su forma, extraer cero mensajes y confirmar el webhook como si no hubiera nada — los seis meses desaparecerían sin aviso, y la petición no se repite. Por eso, cuando llega historial y no se extrae nada, registramos la forma del payload, solo claves y recuentos, sin teléfonos, nombres ni cuerpos de mensaje. Es lo que permite arreglar el parser sin necesitar un segundo cliente para reproducir el problema.

El historial no es una conversación nueva

El webhook history entrega las conversaciones por partes. Cada una trae metadata.phase — 0 para el primer día, 1 para hasta 90 días, 2 para hasta 180 —, un chunk_order y un progress, que llega a 100 al final. Dentro van las conversaciones en threads[], cada mensaje con id, timestamp, tipo y un history_context.status. Meta avisa de que un solo webhook puede describir miles de mensajes y recomienda guardar primero el contenido y procesarlo después, de forma asíncrona.

Las partes llegan desordenadas, y Meta las reenvía. La consecuencia de ingeniería es que nada puede depender de la secuencia: la idempotencia de verdad es el wamid de cada mensaje chocando con un índice único, y el final del proceso es el progress: 100, no la llegada del último chunk_order. Un mensaje sin wamid o sin una hora utilizable debe descartarse — y contarse, para que el log no diga que se importó todo.

La lección más importante, sin embargo, es de producto: el historial no puede pasar por el mismo camino que los mensajes que llegan en directo. Si pasa, cada conversación de hace meses abre una ventana de atención de 24 horas con el reloj equivocado, arranca los plazos de atención y dispara la IA, la respuesta automática, la notificación en el móvil y los webhooks del cliente. Y hay un efecto peor, menos evidente: un “BAJA” que el cliente envió hace cuatro meses, reprocesado como mensaje nuevo, marca el contacto como dado de baja y bloquea campañas para alguien que no lo ha pedido ahora.

En nuestra implementación, el historial es un registro, no una conversación: va directo al almacenamiento, con la hora real de cada mensaje, sin abrir ventana y sin disparar nada. El archivo multimedia que no llegó se convierte en un marcador explícito — foto no disponible, audio no disponible — en lugar de una burbuja de imagen rota, que parecería un fallo del sistema en cuanto el agente hiciera clic.

Teléfonos sin “+” y formatos que cambiaron

Meta envía el teléfono del cliente sin el “+”, en formato wa_id — 34612… en lugar de +34612…. Es el mismo formato de los webhooks de siempre, pero el historial tiene una particularidad: trae conversaciones antiguas, y las conversaciones antiguas traen números guardados de formas distintas. En Brasil, donde los móviles ganaron un noveno dígito, el mismo cliente puede aparecer en el historial con y sin él, y en tu base de datos de una tercera forma; en otros países de América Latina pasa algo parecido cuando el formato de los móviles cambió.

Sin casar los formatos, seis meses de historial se convierten en contactos y conversaciones duplicados a escala: la misma persona partida en dos fichas, cada una con la mitad de la conversación. En nuestra implementación, el historial pasa por el mismo emparejamiento de teléfonos que usa el inbox — con las dos versiones del móvil brasileño — antes de decidir a qué contacto pertenece cada conversación.

Y la decisión por defecto tiene que ser fusionar, no omitir. En un número que ya atendía desde la app y acaba de entrar en la API, lo normal es que ya exista una conversación viva para buena parte de los teléfonos del historial: el cliente escribió ayer, y el mensaje ya llegó por el webhook habitual. El historial debe fusionarse en esa conversación, ordenado por la hora real — no descartarse porque “ya existe”, ni guardarse como un segundo hilo.

Los contactos piden una regla parecida. El webhook smb_app_state_sync trae la agenda del teléfono, con action igual a add o remove. Una recomendación nuestra: usa las altas para completar nombres, e ignora las bajas. Borrar un contacto del sistema porque desapareció de la agenda del móvil del dueño destruiría historial de atención por un evento que no trata de eso.

El dueño responde desde el móvil: los ecos

La coexistencia no es solo la incorporación. Después, el dueño sigue respondiendo desde la app, y cada mensaje que envía desde allí llega al socio por el webhook smb_message_echoes, con remitente, destinatario, id, hora y tipo. Según la referencia, el eco también llega cuando el dueño edita o borra un mensaje en la app. Es continuo, y es lo que mantiene la conversación completa en los dos lados.

Sin procesar los ecos, el agente que usa el inbox ve la pregunta del cliente y ninguna respuesta, y responde otra vez. El cliente recibe la misma información dos veces, de dos personas, a veces con respuestas distintas. Todo eco es un mensaje saliente — es la empresa hablando — y entra en la conversación con la hora en que se envió, como si hubiera salido del propio inbox.

Una regla de ventana que confunde: los mensajes enviados desde la app no crean, no amplían ni afectan a la ventana de atención de la Cloud API, dice la página de la coexistencia. La ventana solo se abre cuando el cliente escribe después de la incorporación. Para quien escribió poco antes de la conexión, la empresa solo puede responder por la API con una plantilla. El dueño puede acabar de hablar con el cliente desde el móvil, y aun así el inbox necesita una plantilla para escribirle.

Y están los dispositivos vinculados. La empresa puede mantener hasta cuatro dispositivos acompañantes, pero en la incorporación se desvinculan todos, y el dueño tiene que volver a vincular los que usa. Todos están soportados salvo WhatsApp para Windows y WhatsApp para WearOS — y los mensajes enviados desde un acompañante no soportado no disparan webhooks. En la práctica, lo que un empleado responde desde la app de Windows no aparece en el sistema. Conviene avisar al cliente antes de conectar.

Qué cambia en la app después de conectar

Algunas funciones de la app se desactivan en los chats individuales cuando el número entra en coexistencia: mensajes temporales, visualización única y ubicación en tiempo real. Las listas de difusión también: no se pueden crear nuevas, y las existentes quedan solo de lectura. Para la pequeña empresa que hace promoción con listas de difusión, es el cambio que más pesa — la promoción pasa a hacerse con plantillas, por la API, con las reglas y el coste de las plantillas.

Otras funciones siguen en la app pero no existen en la API: grupos, llamadas de voz y vídeo, catálogo, pedidos, estados, mensajes de bienvenida y de ausencia, respuestas rápidas y etiquetas. El dueño sigue usando todo eso en el móvil; el inbox no lo ve. La comparación de la página sirve para ajustar expectativas: la coexistencia suma la API a la app, no convierte la app en una API.

Y algunos recursos de la plataforma quedan fuera del alcance de los números de la app. La documentación de grupos dice que no están disponibles para números de la app WhatsApp Business. La API de llamadas exige que el número esté en uso con la Cloud API y no con la app. Y Meta no concede el distintivo de cuenta de empresa oficial a números de la app. Quien piense usar alguno de estos recursos necesitará, en algún momento, la migración completa.

Throughput, facturación y el límite que vale

El throughput de un número en coexistencia es fijo. Según la página Throughput, los números usados a la vez en la app y en la Cloud API tienen “a fixed throughput of 20 mps” — 20 mensajes por segundo, contando entrada y salida, de todos los tipos. Para comparar, un número solo en la Cloud API empieza en 80 y puede subir automáticamente hasta 1.000. Pasarse del techo devuelve el error 130429, como en cualquier número.

Para la operación típica de una pequeña o mediana empresa, 20 por segundo sobra: son 1.200 mensajes por minuto. El techo aparece en campañas grandes, y entonces se convierte en planificación — una lista de 50.000 contactos tarda bastante más que unos minutos en salir, y la atención en directo comparte el mismo throughput con el envío masivo. El límite de mensajes por portfolio, que cuenta destinatarios únicos fuera de la ventana en 24 horas, vale con normalidad.

La facturación separa los dos extremos. La página de la coexistencia dice que los mensajes enviados desde la app siguen siendo gratuitos, y los enviados por la Cloud API siguen el precio de la Cloud API. Desde el 1 de octubre de 2026, eso incluye la atención: cada número tiene 1.000 mensajes de atención gratis al mes, y a partir del 1.001 Meta cobra. Utility y marketing se cobran por mensaje entregado, con la ventana abierta o cerrada.

La lectura práctica, que es nuestra y no una regla de Meta: responder desde la app no cuesta nada; responder desde el inbox consume la franquicia mensual de atención del número y, después, cuesta; y el envío proactivo, con plantillas, solo existe por la API. Eso ayuda a decidir quién atiende por dónde — y explica por qué algunas empresas dejan al dueño en la app y al equipo en el inbox.

Mantenerse conectado, desconectar y cambiar de socio

La integración depende del móvil. El webhook account_update trae el motivo cuando se cae la conexión, y dos de ellos son de inactividad: PRIMARY_INACTIVITY, cuando el dispositivo principal pasa unos 14 días sin uso, y COMPANION_INACTIVITY, unos 30 días. El Centro de ayuda de WhatsApp dice lo mismo sobre los dispositivos vinculados en general. Para el dueño, la regla es sencilla: el móvil con la app tiene que seguir en uso.

Cambiar de móvil, reinstalar la app o volver a registrar el número desconecta la Cloud API automáticamente, con el evento ACCOUNT_OFFBOARDED. En el nuevo registro, el dueño ve una opción ya marcada para reconectar, y el proceso suele tardar pocos minutos, terminando con ACCOUNT_RECONNECTED. Durante la reconexión, el envío por la API queda suspendido. Quien está suscrito a account_update lo sabe al momento; quien no, se entera por los mensajes que no salieron.

Desconectar a propósito se hace desde la app, no desde la API. La página de la coexistencia dice que la API de baja no funciona para un número en uso en la app y en la Cloud API; el camino es el propio dueño, en los ajustes de la cuenta, en el apartado de la plataforma para empresas. El socio recibe PARTNER_REMOVED, con un disconnection_info que indica el motivo y quién lo inició.

Por último, el nuevo modelo de cuentas de Meta, que entró en vigor el 23 de septiembre de 2026, trata la coexistencia como una excepción. En la incorporación, Meta convierte la cuenta existente en una cuenta de mensajería compatible y no crea la cuenta de mensajería propia de cada socio, como hace en el flujo normal. El flujo tampoco admite cambio de socio — el error 2655093 pide desconectar primero el actual —, y las conversaciones con varios socios no soportan números de la app. En la práctica, un número en coexistencia trabaja con un socio cada vez.