# 14 · La cuenta de Meta paso a paso y la coexistencia con la app del móvil

Dos partes. La **A** la hacéis **una sola vez como plataforma**. La **B** es lo que hace cada negocio —incluido el vuestro— para conectar **el número que ya usa en el móvil sin dejar de usarlo**.

> **Qué está verificado.** Lo de la coexistencia (requisitos, avisos, límites, pasos de la ventana de Meta) sale de la documentación oficial de Meta para desarrolladores. Los pasos de la Parte A sobre el portfolio y la verificación del negocio, y el nombre exacto de algunos menús, son de uso general: **Meta cambia sus pantallas con frecuencia**; si un menú no está donde se indica, buscad el nombre en la ayuda de Meta. Nada de esto se ha ejecutado contra una cuenta real de Meta: es lo pendiente antes de salir a producción ([10](10-pruebas-y-produccion.md)).

---

## Parte A · Lo que hace la plataforma, una vez

### A1. Crear el portfolio comercial («Meta Business»)

1. Entrad en **business.facebook.com** con una cuenta de Facebook **personal de una persona real** de la empresa (Meta lo exige para administrar; no se publica nada con ella). Activad la verificación en dos pasos.
2. **Crear una cuenta / portfolio**: nombre de la empresa, vuestro nombre y un correo **corporativo**.
3. En **Configuración del negocio → Información del negocio** rellenad el **nombre legal** tal y como figura en los registros oficiales, la dirección, el teléfono y la web.
4. En **Personas** añadid **al menos otro administrador** (si perdéis el acceso, perdéis la cuenta).

### A2. Verificar la empresa

**Configuración del negocio → Centro de seguridad → Verificación de la empresa → Iniciar verificación.**

- Datos que Meta pide: nombre legal, dirección, teléfono, correo y sitio web (ver la [guía de Meta](https://developers.facebook.com/docs/whatsapp/solution-providers/get-started-for-tech-providers)). Si no encuentra la empresa, pide **documentos que acrediten nombre legal y dirección** (en España suelen valer escrituras, certificado de alta censal o una factura de suministros a nombre de la empresa). Los datos deben **coincidir exactamente** con los documentos.
- Tiene que estar terminada antes de la revisión de la app (A4). No hay plazo fijo: puede tardar desde minutos hasta varios días.

### A3. Crear la App de Meta

1. **developers.facebook.com → Mis apps → Crear app**, con el caso de uso de **WhatsApp**, y conectadla al portfolio de A1 (se puede crear desde ahí mismo).
2. En **Configuración de la app** añadid **icono**, **política de privacidad** (URL pública) y **categoría**.

### A4. Ser Tech Provider

Es lo que permite usar **Embedded Signup** (la ventana de Meta con la que cada negocio conecta su número). Pasos según la [documentación de Meta](https://developers.facebook.com/docs/whatsapp/solution-providers/get-started-for-tech-providers):

1. En el panel de la app: **Casos de uso → Personalizar → WhatsApp → Incorporación como Tech Provider**.
2. Completad la **verificación del negocio** (A2).
3. Preparad **dos vídeos**: uno enviando un mensaje desde vuestra aplicación y recibiéndolo en WhatsApp; otro creando una plantilla desde vuestra aplicación. (Alternativa: grabar el script cURL de «API Setup» y la creación de una plantilla en WhatsApp Manager.) Para el primero, usad la pantalla de plantillas y el chat embebidos del gateway.
4. Pedid **acceso avanzado** a `whatsapp_business_messaging` y `whatsapp_business_management` y pulsad **Iniciar revisión de la app**.
5. Elegid **«Incorporar sin socio»**. Al confirmaros, tendréis acceso a todos los canales de soporte de Meta.

Mientras la revisión no está aprobada, la app funciona en modo desarrollo: solo las personas con un rol en la app pueden usarla. Con eso se puede probar el alta, pero no abrirla a clientes.

### A5. Configurar Embedded Signup y el webhook

1. **Inicio de sesión de Facebook para empresas → Configuraciones → Crear** una configuración para **WhatsApp Embedded Signup**, con los permisos `whatsapp_business_management` y `whatsapp_business_messaging`. El identificador que os da es **`META_CONFIG_ID`**.
2. En la configuración del inicio de sesión, añadid como **dominios permitidos para el SDK de JavaScript** el dominio donde sirvais la pantalla de alta (el de la API, `wa.<dominio>`).
3. **WhatsApp → Configuración → Webhook**: URL `https://hooks.<dominio>/webhooks/meta`, y como **token de verificación** el valor de `META_VERIFY_TOKEN`. Suscribid estos campos:
   - los de siempre: `messages`, `message_template_status_update`, `message_template_quality_update`, `message_template_components_update`, `template_category_update`, `phone_number_name_update`, `phone_number_quality_update`;
   - **para la coexistencia** (obligatorios): `smb_message_echoes`, `history`, `smb_app_state_sync` y `account_update`.
4. En el servidor poned `META_APP_ID`, `META_APP_SECRET`, `META_CONFIG_ID` y `META_VERIFY_TOKEN`. La consola de administración (Panel) comprueba que existen.

> **Versión de Embedded Signup.** Meta retira las versiones 2 y 3 el 15 de octubre de 2026. El gateway usa la 4; en la 5 la conexión de números de la app Business viene activada por defecto y no necesita `featureType`.

---

## Parte B · Conectar el número que ya usas en el móvil (coexistencia)

Sirve para **vuestro propio número** y para el de cualquier cliente. Es el mismo flujo: nada especial para vosotros.

### Requisitos

- El número está en la **app WhatsApp Business** (no en WhatsApp normal) y la versión de la app es la **2.24.17 o superior**. Si hoy usáis WhatsApp normal, **pasad primero esa cuenta a WhatsApp Business** desde la propia app.
- Un **portfolio comercial** (A1) del negocio. El **WABA se crea durante el alta**: en la ventana de Meta se elige o se crea el portfolio y la cuenta de WhatsApp Business. La empresa sigue siendo la propietaria de sus activos.
- El móvil con la app a mano durante el alta.
- Una **tarjeta** para WhatsApp Manager: Meta factura directamente al negocio los mensajes que envía la API.
- Alta en el sistema: tenant, licencia y app habilitada ([11](11-administracion.md)).

### Pasos

1. En la aplicación, **Configuración → Conectar un número → «Uso este número en la app WhatsApp Business»**. (Desde la consola de administración, un técnico puede usar la **conexión manual** marcando «también está en la app»; para clientes reales, el alta de la ventana de Meta.)
2. En la ventana de Meta, según su documentación: elegid **conectar una cuenta de WhatsApp Business existente**, escribid el número, **copiad el código** que muestra, **aceptad el mensaje** de la cuenta oficial de empresa en la app y tocad **Conectar**, continuad por la pantalla de conexión con la plataforma, **decidid si compartís el historial** y pegad el código para terminar.
3. Esperad a que el gateway termine: el número aparece **«Con app Business»** y, al lado, el estado del historial.

### Qué hace el gateway por vosotros

| Qué pasa | Qué hace el gateway |
| --- | --- |
| El alta termina | Suscribe la cuenta a los avisos, **no registra el número** (ya lo está en la app) y **pide a Meta los contactos y el historial**. Meta solo lo permite **una vez** y en las **24 horas** siguientes al alta; si se pasa el plazo, hay que desconectar y repetir el alta |
| Alguien escribe **desde el móvil** | Llega un aviso de Meta y el gateway guarda el mensaje como **enviado desde la app** (`via: business_app`) en la conversación y emite **`whatsapp.message.sent_from_app`**. No abre la ventana de 24 h ni cuenta contra el límite de mensajes de la licencia |
| Editan o borran un mensaje en la app | El texto se actualiza (`edit`) o pasa a «[mensaje eliminado]» (`revoke`) |
| Llega el historial (hasta **180 días**) | Se importa **sin efectos**: sin eventos, sin tocar mensajes no leídos ni la licencia, sin reenviar nada. Cada mensaje queda con `via: history` y su estado real. Los archivos solo se descargan si son de los últimos 14 días. El progreso se ve en `history_sync` del número |
| Cambian los contactos de la agenda de la app | El nombre rellena el del contacto **solo si no tenía ya uno**; no se borra nada |
| El negocio pulsa **Desconectar** en la app, cambia de dispositivo o se vuelve a registrar | El número pasa a desconectado, el token se revoca y se emite `whatsapp.number.disconnected` con el motivo (`reason`, `initiated_by`). `ACCOUNT_RECONNECTED` lo recupera |

### Lo que cambia en el móvil y en la API

Según la documentación de Meta:

- **No se sincronizan los grupos.** Los **mensajes temporales, de una sola vista y la ubicación en tiempo real** no se admiten. Las **listas de difusión** se desactivan (las existentes quedan en solo lectura). Las llamadas, el perfil de empresa, los canales y las herramientas de la app no están en la API.
- La velocidad de envío del número queda fija en **20 mensajes por segundo**, que es lo que ya usa el gateway.
- **Los mensajes que escribe una persona desde la app siguen siendo gratis; los que envía la API se facturan** con las tarifas de la API.
- **Hay que seguir usando la app.** Meta desconecta el número si la app principal pasa unos 14 días sin actividad (`PRIMARY_INACTIVITY`) o un dispositivo vinculado unos 30 (`COMPANION_INACTIVITY`). Si pasa, el gateway avisa con `whatsapp.number.disconnected`.
- Los clientes de Windows y de WearOS no están admitidos: lo que se escriba desde ellos no genera aviso.
- Un cliente que edita o borra un mensaje a la empresa genera aviso solo dentro de 15 minutos (edición) o 2 días (borrado).

### Cómo afecta a un bot

Cuando una persona escribe desde el móvil, el bot **debe callarse**: el evento `whatsapp.message.sent_from_app` es la señal de que alguien ha tomado la conversación. Suscribid al bot a ese evento y dejad de responder a esa conversación hasta que se cierre.

### Si algo no sale

| Síntoma | Qué mirar |
| --- | --- |
| Meta no ofrece conectar una cuenta existente | El número no está en WhatsApp Business, la app es antigua o el país no lo admite. Con Embedded Signup v4 la sesión se crea con `featureType` (el gateway lo hace por vosotros) |
| El alta falla con «varios números» | La cuenta tiene más de un número y Meta no dijo cuál. Repetid el alta indicando el número o dejad un solo número |
| `history_sync` en `declined` | El negocio decidió no compartir el historial (código 2593109). Para pedirlo otra vez hay que desconectar y repetir el alta |
| `history_sync` en `error` | Meta rechazó la petición. Se puede continuar sin historial; para reintentarlo, desconectar y repetir el alta |
| No llegan los mensajes escritos desde el móvil | Faltan las suscripciones `smb_message_echoes`, `history`, `smb_app_state_sync` y `account_update` en el webhook de la app (A5) |