📗 Conecta tu WhatsApp a la API oficial de Meta

PASO 1Crea tu cuenta de desarrollador y tu app

1. Abre developers.facebook.com ↗ e inicia sesión con tu Facebook.
2. Si es tu primera vez: botón «Comenzar» (arriba a la derecha) → te pide verificar tu cuenta con un código por SMS y elegir ocupación (elige «Desarrollador» u «Otro» — da igual).
3. Arriba a la derecha: Mis apps → Crear app.
4. Te pregunta «¿Qué quieres que haga tu app?». Meta cambió esta pantalla: ahora elige el caso de uso «Conectar en WhatsApp» si aparece. Si no lo ves, elige «Otro» → luego tipo «Negocios» (Business).
5. Importante: ya no existe «Agregar producto». Los permisos ahora cuelgan del caso de uso. Si más adelante te falta algo, se agrega desde el botón «Añadir casos de uso» en el panel de tu app.
6. Nombre de la app: el de tu negocio (ej. MiTienda CRM) + tu correo → Crear app (te pide tu contraseña de Facebook).

PASO 2Agrega WhatsApp a tu app

1. Al crear la app caes en el panel «Agregar productos a tu app». Busca la tarjeta WhatsApp → botón «Configurar».
2. Te pedirá elegir o crear un portafolio comercial (Business portfolio). Si no tienes: «Crear portafolio comercial» → nombre del negocio, tu nombre y correo → Crear.
3. Al terminar, en el menú izquierdo de la app aparece WhatsApp → Configuración de la API. Esa pantalla es tu centro de control: ahí están casi todos los datos.

PASO 3Copia el ① Phone Number ID y el ② WABA ID

En WhatsApp → Configuración de la API verás la sección «Enviar y recibir mensajes»:

1. En el selector «De» (From) aparece el número de prueba que Meta te regala (algo como «Test number +1 555 …»). Puedes usarlo para probar TODO gratis.
2. Justo debajo del selector «De» está: «Identificador de número de teléfono» (Phone number ID) — un número largo tipo 123456789012345. Cópialo con el ícono de copiar. Ese es tu ① Phone Number ID.
3. Debajo del anterior está: «Identificador de la cuenta de WhatsApp Business» (WhatsApp Business Account ID). Cópialo. Ese es tu ② WABA ID.

PASO 4Genera el ③ Token PERMANENTE (el paso donde todos se pierden)

1. Abre business.facebook.com → clic en el engranaje ⚙️ «Configuración» (esquina inferior izquierda). Se abre «Configuración del negocio».
2. Menú izquierdo → Usuarios → Usuarios del sistema. (Si te pide activar la verificación en dos pasos de tu Facebook, actívala — es requisito de Meta.)
3. Botón «Agregar» → nombre: crm-zyneria → rol: Administrador → «Crear usuario del sistema» (acepta las condiciones si aparecen).
4. Con el usuario seleccionado, botón «Agregar activos» → pestaña Apps → selecciona TU app → activa el interruptor «Administrar app» → Guardar cambios.
5. Ahora botón «Generar token nuevo»:
   • App: la tuya.
   • Caducidad del token: «Nunca».
   • Permisos — busca en la lista y marca SOLO estos dos:
     ✅ whatsapp_business_messaging
     ✅ whatsapp_business_management
   • Clic en «Generar token».
6. Meta te muestra el token UNA SOLA VEZ: es un texto largo que empieza por EAA…. Cópialo y guárdalo en un lugar seguro. Ese es tu ③ Token permanente.

PASO 5Copia el ④ App Secret

1. Vuelve a developers.facebook.com ↗ → Mis apps → tu app.
2. Menú izquierdo → Configuración de la app → Básica.
3. Campo «Clave secreta de la app» (App secret) → botón «Mostrar» → escribe tu contraseña de Facebook → copia el texto (32 caracteres). Ese es tu ④ App Secret.

Sirve para que el CRM verifique que cada mensaje entrante viene de verdad de Meta (seguridad). Se guarda cifrado.

PASO 6Inventa tu ⑤ Verify Token

Es una contraseña que tú inventas (no viene de Meta). Ejemplo: zyneria-mitienda-2026. Sin espacios. La escribirás dos veces — en el CRM (Paso 7) y en Meta (Paso 8) — y debe ser idéntica en ambas.

PASO 7Pega los 5 datos en el CRM Oficial

1. Entra a oficial.zyneria.com → crea tu cuenta (Sign up) o inicia sesión.
2. Ve a Settings → WhatsApp y llena:

• Phone Number ID → el ① del Paso 3
• WhatsApp Business Account ID → el ② del Paso 3
• Permanent Access Token → el ③ del Paso 4 (el que empieza por EAA…)
• Webhook Verify Token → el ⑤ que inventaste
• App Secret → el ④ del Paso 5
• PIN (opcional) → solo para número REAL de producción: es el PIN de verificación en dos pasos del número (se crea/ve en WhatsApp Manager → tu número → Verificación en dos pasos). Con el número de PRUEBA déjalo vacío.

Clic en Guardar — el CRM valida tus credenciales directamente contra Meta. Si algo está mal copiado te lo dice ahí mismo.

PASO 8Conecta el Webhook (para RECIBIR mensajes)

1. En developers.facebook.com ↗ → tu app → menú izquierdo WhatsApp → Configuración (Configuration — ojo: es distinto a «Configuración de la API»).
2. Sección Webhook → botón «Editar»:
   • URL de devolución de llamada: https://oficial.zyneria.com/api/whatsapp/webhook
   • Identificador de verificación: tu ⑤ Verify Token (idéntico al del CRM, sin espacios extra)
   • Clic «Verificar y guardar» — si dice error, revisa que el Verify Token sea EXACTO y que ya lo hayas guardado antes en el CRM (Paso 7).
3. En la misma pantalla, «Campos de webhook» → botón «Administrar» → busca messages → Suscribirse ✅ (opcional pero recomendado: también message_template_status_update).

🚧 Si te quedas trabado

El número dice «No registrado» y el botón no responde

Casi siempre es porque ese número todavía tiene WhatsApp activo. Un número no puede estar en la app y en la API al mismo tiempo: elimina la cuenta desde la app (Ajustes → Cuenta → Eliminar mi cuenta), espera unos minutos y vuelve a registrarlo.

Llevo días en «Pending review»

Esa revisión es del nombre visible, y no te impide registrar el número ni enviar mensajes — mientras no la aprueben, tus clientes ven el número en lugar del nombre. Si se demora más de una semana, revisa que el nombre sea el del negocio real: los genéricos como «crm», «bot» o «ventas» se rechazan.

Los mensajes salen pero no me llegan los que me escriben

Falta el webhook (paso 8) o el interruptor «Suscribir webhooks» está apagado en la pantalla de configuración de producción. Sin eso, enviar funciona y recibir no.

Solo me deja 2 números

Es el límite hasta que completes la verificación del negocio ↗. Después suben a 20. Necesitas un documento legal a nombre de la empresa — en Colombia el RUT, en Ecuador el RUC.

PASO 9¡Prueba! (1 minuto)

1. Desde tu celular (agregado como destinatario si usas el número de prueba), escríbele un WhatsApp a tu número conectado.
2. El mensaje aparece en la bandeja (Inbox) del CRM Oficial en segundos.
3. Respóndele desde el CRM → llega instantáneo. 🎉 Conexión completa.

🆘 Errores comunes (y su cura)

• «Verification token mismatch» al guardar el webhook → el Verify Token de Meta y el del CRM no son idénticos (espacios al copiar). Guarda primero en el CRM, luego en Meta.
• «Meta API error» al guardar en el CRM → el token no es el permanente (copiaste el temporal de 24h), o le faltan los 2 permisos del Paso 4, o el Phone Number ID tiene un dígito mal.
• No llegan mensajes entrantes → falta suscribirse al campo messages (Paso 8.3) o falta el App Secret en el CRM.
• Error (#131030) «Recipient not in allowed list» → estás usando el número de PRUEBA y el destinatario no está agregado/verificado (Paso 3, recuadro verde).
• «Este número ya está vinculado a otra cuenta» → cada número solo puede vivir en UNA cuenta del CRM.
• No encuentro «Usuarios del sistema» → estás en facebook.com y no en business.facebook.com → Configuración del negocio; o tu Facebook no tiene verificación en dos pasos activa (actívala y reintenta).

📌 Cómo funciona la API oficial (léelo una vez)

• Responder es libre: cuando un cliente te escribe, tienes una ventana de 24 horas para responderle lo que quieras (texto, fotos, documentos).
• Iniciar tú la conversación (o responder pasadas las 24h) requiere plantillas aprobadas por Meta — se crean y envían desde el CRM (sección Templates; aprobación típica en minutos u horas).
• Costos de Meta: cobra por conversación iniciada por plantilla (centavos de dólar, según país). Responder dentro de la ventana de servicio es gratis. Tarifas: business.whatsapp.com/products/platform-pricing
• Límites: arrancas pudiendo iniciar conversación con 250–1.000 clientes únicos/día; sube solo con buen uso, y con verificación del negocio escala a 10k+/día.
• Sin bloqueos: automatizar es el uso PREVISTO de esta API. Las reglas: usar plantillas aprobadas y cuidar la calificación de calidad del número.