> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryvo.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Conectar WhatsApp Business
> Conecta el número de WhatsApp de tu negocio para que tu agente conteste los mensajes.
Con esta integración, tu agente del Engine contesta los mensajes que lleguen al número de WhatsApp de tu negocio, usando la **Cloud API de Meta** con tu propia app. Meta aloja la API, así que no dependes de ningún proveedor intermedio: Ryvo habla directo con WhatsApp.
Para conectarlo necesitas cinco datos de Meta, que reúnes en los pasos 1 a 4, y después los pegas en Ryvo en el paso 5:
| Dato | Dónde sale |
| ------------------------------------------ | ---------- |
| **ID de la app de Meta** | Paso 1 |
| **App secret** | Paso 4 |
| **WABA ID** (WhatsApp Business Account ID) | Paso 2 |
| **Phone number ID** | Paso 2 |
| **Token permanente** | Paso 3 |
Meta cambia su interfaz con frecuencia. Si tu pantalla no se ve igual que las capturas, busca la sección de configuración de la API de WhatsApp de tu app: los IDs siempre aparecen junto al número seleccionado.
## Qué necesitas
1. Una cuenta de **Meta Business** (portafolio de negocio). Para pasar de pruebas a producción, Meta pide verificarla.
2. Un número de teléfono que **no esté ligado a otra cuenta de WhatsApp**, ni a la app de WhatsApp normal ni a la de WhatsApp Business. Si tu número está activo en la app del celular, no lo registres por este flujo: escríbenos a [soporte@ryvo.so](mailto:soporte@ryvo.so) para ver la mejor forma de migrarlo.
3. Un **agente publicado** en tu cuenta de Ryvo. WhatsApp siempre contesta con la versión publicada, nunca con el borrador.
## Paso 1: crea (o elige) la app en Meta for Developers
En [developers.facebook.com/apps](https://developers.facebook.com/apps) elige una app existente o da clic en **Crear app**.
Si es nueva, escribe el nombre de la app y un correo de contacto, y da **Siguiente**.
En la pantalla de casos de uso, marca **Conectar con clientes a través de WhatsApp** y da **Siguiente**.
Selecciona el portafolio que es (o será) dueño de tu cuenta de WhatsApp Business. Si no tienes uno, Meta te deja crearlo aquí.
Revisa los datos, el caso de uso y el portafolio, y da **Crear app**.
Ya dentro de la app, el **ID de la app** aparece en la barra superior del panel (junto a "App ID"). Cópialo: es el primer campo del formulario de Ryvo.
## Paso 2: registra tu número y copia los dos IDs
En el menú de la app, entra a **Casos de uso**, busca **Conectar con clientes a través de WhatsApp** y da **Personalizar**.
En la interfaz nueva de Meta, ve a **Configuración básica → Paso 2. Configuración de producción** y abre **Registra tu número de WhatsApp**. En apps más viejas, la misma pantalla está en **WhatsApp → Configuración de la API**.
Elige un número existente en el selector, o da **Agregar número**. Si es nuevo, escribe el nombre que verán tus clientes, el número, elige verificación por SMS o llamada y captura el código que te manda Meta.
Con el número seleccionado, la pantalla muestra el **WhatsApp Business Account ID** (el WABA ID) y el **Phone Number ID**. Copia los dos.
## Paso 3: genera un token permanente
El token que Meta muestra por omisión caduca en 24 horas. Para que la conexión no se caiga, genera uno **sin expiración** desde un usuario del sistema.
En [business.facebook.com/settings](https://business.facebook.com/settings) elige el portafolio dueño de tu WABA y ve a **Usuarios → Usuarios del sistema**. Si ya tienes uno, selecciónalo; si no, da **Agregar**.
Ponle un nombre (por ejemplo, "Ryvo WhatsApp"), elige el rol **Administrador** y da **Crear usuario del sistema**.
Con el usuario seleccionado, da **Asignar activos**: agrega tu app de Meta y tu cuenta de WhatsApp Business con **control total**. Después da **Generar token**.
Selecciona la app que creaste en el paso 1 y da **Siguiente**.
En la caducidad del token elige **Nunca** y da **Siguiente**.
Marca `whatsapp_business_messaging` y `whatsapp_business_management`, y genera el token.
Da **Copiar** y guárdalo en un lugar seguro: Meta no lo vuelve a mostrar.
Quien tenga ese token puede mandar mensajes desde tu número. No lo compartas por chat ni por correo; pégalo sólo en el formulario de Ryvo, donde se guarda cifrado.
## Paso 4: copia el App secret
En tu app de Meta, ve a **Configuración de la app → Básica** y da **Mostrar** junto a **Clave secreta de la app** (Meta puede pedirte tu contraseña). Cópiala. Ryvo la usa para verificar que cada mensaje que llega al webhook viene de Meta y no de alguien más.
## Paso 5: conecta en Ryvo
En Ryvo, ve a **Configuración → Integraciones**, busca la tarjeta **WhatsApp Business** y da clic en **Configurar**. Se abre una página con los pasos a la izquierda y el formulario a la derecha:
Pega los cinco datos: **ID de la app de Meta** (paso 1), **App secret** (paso 4), **WABA ID** y **Phone number ID** (paso 2) y **Token permanente** (paso 3). Al dar **Crear canal de WhatsApp**, Ryvo valida las credenciales contra Meta antes de guardar nada. Si algo está mal, el error aparece debajo del campo que hay que corregir.
Selecciona el agente que va a contestar (sólo aparecen los publicados) y da **Asignar agente**. Puedes dejarlo para después, pero mientras no haya agente el número recibe mensajes sin contestar.
Ryvo intenta configurar el webhook de tu app y suscribir tu WABA automáticamente. Si lo logra, no tienes que tocar nada más en Meta. Si no, la misma pantalla te da la **URL de callback** y el **verify token** para hacerlo a mano (siguiente sección).
## Si Ryvo no pudo configurar el webhook solo
La pantalla de WhatsApp Business (Configuración → Integraciones → Configurar) te muestra la **URL de callback** y el **verify token**. Completa estos pasos en tu app de Meta:
En tu app, ve a **WhatsApp → Configuración**. En la sección **Webhook**, pega la URL de callback y el verify token y da **Verificar y guardar**.
En la lista de campos del webhook, activa **messages**. Sin este campo, Ryvo no recibe los mensajes de tus clientes.
En la pantalla del paso 2 (configuración de producción), activa **Suscribir webhooks** junto a tu cuenta de WhatsApp Business. Si no ves el interruptor, escríbenos y lo hacemos por ti.
## Cómo probar
Manda un "hola" desde tu celular al número que conectaste. Si todo quedó bien, el agente contesta en unos segundos y la conversación aparece en **Conversaciones** como cualquier otra.
## Estados de la conexión
| Estado | Qué significa |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Esperando el primer mensaje** | La conexión quedó lista; todavía no llega ningún mensaje. |
| **Activo** | Ya hay conversación entrando y saliendo. |
| **Pausado** | La pausaste tú; el número deja de contestar hasta que la reanudes. |
| **Token inválido** | Meta rechazó el token (por ejemplo, lo revocaste). Da **Reconectar** y genera uno nuevo desde el paso 3. |
## Límites de hoy
* **Sólo texto.** Si un cliente manda audio, imagen o documento, recibe un aviso de que el agente todavía no los procesa.
* **Un número por cuenta.** Para varios números, escríbenos a [soporte@ryvo.so](mailto:soporte@ryvo.so).
* El agente contesta con su **versión publicada**; los cambios en el borrador no aplican hasta que publiques.
* Aplica la **ventana de 24 horas** de Meta: el agente sólo responde a mensajes de tus clientes; no inicia conversaciones ni manda plantillas.
* La cuenta necesita el **Engine activo** y **saldo**; si el saldo se agota, el agente deja de contestar igual que en voz o chat.
## Problemas frecuentes
| Síntoma | Causa probable | Qué hacer |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| "Meta rechazó el token o no tiene permiso sobre ese número" | El usuario del sistema no tiene asignada la WABA, o faltan los permisos del paso 3 | Vuelve al paso 3: asigna la WABA con control total y genera un token nuevo con los dos permisos |
| "No encontramos ese Phone number ID o WABA ID" | Copiaste un ID de otra app o de otro portafolio | Revisa que los dos IDs salgan de la pantalla del paso 2, con el mismo número seleccionado |
| El agente no contesta y la tarjeta dice "Esperando el primer mensaje" | El webhook no quedó configurado o falta la suscripción de la WABA | Completa la sección del webhook manual |
| Contesta a textos pero no a audios | Es el límite de hoy | Nada que configurar; el aviso al cliente es automático |