Skip to main content
Las apps personalizadas te permiten dar acceso a una integración a números de teléfono de WhatsApp Business seleccionados y a las API de YCloud. Cada app tiene su propia clave de API, permisos de API y configuración de webhook. Usa una app personalizada cuando quieras limitar una integración a los recursos y funciones que necesita.

​
Antes de comenzar

Asegúrate de que:
  • Tu cuenta use un plan de pago de YCloud. Las apps personalizadas no están disponibles en el plan gratuito.
  • Tu rol pueda acceder a Desarrolladores > Apps personalizadas en el panel de control de YCloud.
  • Los números de teléfono de WhatsApp Business que la app necesita ya estén disponibles en tu cuenta de YCloud.
  • Sepas qué permisos de API necesita la integración.
  • Tengas un endpoint HTTPS accesible públicamente si la app necesita eventos de webhook.
Guarda la clave de API de la app y el secreto de firma del webhook en un gestor de secretos. Nunca los expongas en código del lado del cliente, registros, capturas de pantalla o control de versiones.

​
Crear una app

  1. Inicia sesión en el panel de control de YCloud.
  2. Ve a Desarrolladores > Apps personalizadas.
  3. Haz clic en Crear app.
Página de apps personalizadas en el panel de control de YCloud con el botón Crear app.
  1. Introduce un Nombre de la app. El nombre puede contener hasta 64 caracteres.
  2. Opcional: Introduce una Descripción de hasta 512 caracteres para que tu equipo sepa para qué se utiliza la app.
  3. Haz clic en Crear.
Cuadro de diálogo Crear app con los campos Nombre de la app y Descripción.

Enter an app name and, optionally, a description before selecting Create.

YCloud asigna a la app un ID de app de solo lectura. Una app nueva está desactivada hasta que la habilites explícitamente. Configura sus recursos, acceso a la API y eventos de webhook antes de habilitarla.

​
Asignar números de teléfono de WhatsApp

Asigna solo los números de teléfono a los que la integración necesita acceder.
  1. Abre la app y selecciona Recursos.
  2. Haz clic en Añadir números de teléfono.
Sección Recursos de una app personalizada con el botón Añadir números de teléfono.
  1. Busca un número por su nombre de Business Manager, ID de WABA, nombre de WABA o número de teléfono.
  2. Selecciona uno o más números de teléfono de WhatsApp Business.
  3. Haz clic en Confirmar.
La ventana de selección también muestra el estado de vinculación y la calificación de calidad de cada número cuando esa información está disponible.
Cuadro de diálogo Añadir números de teléfono que muestra los números de teléfono de WhatsApp Business disponibles, el estado de vinculación y la calificación de calidad.
Los números seleccionados aparecen ahora en la lista de recursos de la app.

​
Configurar la clave de API y los permisos

YCloud muestra la clave de API de la app en Clave de API y permisos. Las claves de apps personalizadas comienzan con yc_ak_. Usa la acción de copiar para guardar la clave de forma segura y luego añade solo los permisos que la integración requiera.
Sección Clave de API y permisos para una app personalizada.
  1. Selecciona Clave de API y permisos.
  2. En Permisos de API, haz clic en Añadir permisos.
  3. Filtra por categoría o busca por nombre de permiso o alcance.
  4. Selecciona cada permiso requerido. Por ejemplo, los permisos de contactos se dividen en alcances de lectura, creación o actualización y eliminación.
  5. Haz clic en Confirmar.
Cuadro de diálogo Editar permisos que muestra los alcances de permisos de contactos.
Envía la clave generada en el encabezado X-API-Key y úsala únicamente desde código confiable del lado del servidor. YCloud comprueba que la app esté activa y que la solicitud coincida con uno de sus permisos de API seleccionados. Cuando una API opera sobre un recurso de WhatsApp, YCloud también comprueba que la app pueda acceder al número de teléfono o WABA correspondiente. No todas las API de YCloud están disponibles para apps personalizadas. Una API que no aparezca en el selector de permisos se denegará para una clave de app personalizada. Las claves de apps personalizadas tampoco se pueden combinar con el encabezado X-Managed-Account-ID. Consulta Autenticación para ver las pautas sobre el encabezado de solicitud y el manejo de credenciales.
La sección de clave de API incluye una acción para generar una clave de reemplazo. Según la opción que elijas durante la regeneración, la clave anterior se revocará de inmediato o permanecerá disponible durante un período de transición de una hora. Actualiza cada servicio que use la clave antes de que finalice el período de transición.

​
Configurar webhooks

Configura un destino dedicado para los eventos que necesita esta app. Los webhooks de la app son independientes de los endpoints de webhook configurados en Desarrolladores > Webhooks.
  1. Selecciona Webhook.
  2. Introduce tu endpoint HTTPS público en URL del endpoint y guárdalo.
  3. Guarda el Secreto de firma generado de forma segura.
  4. En Eventos añadidos, haz clic en Añadir eventos.
Sección Webhook con los ajustes de URL del endpoint, Secreto de firma y Eventos añadidos.
  1. Filtra por categoría o busca por nombre de evento o tipo de evento.
  2. Selecciona los eventos que tu endpoint debe recibir.
  3. Si un evento ofrece opciones de alcance de datos, elige el alcance que se adapte a tu integración.
  4. Haz clic en Confirmar.
Cuadro de diálogo Añadir eventos de webhook que muestra los eventos de contactos disponibles.
YCloud entrega únicamente los eventos seleccionados al endpoint de una app activa. Los eventos de WhatsApp se filtran según los números de teléfono asignados a la app o sus WABA principales. La configuración del alcance de datos específica de cada evento puede limitar aún más la entrega a los datos atribuidos a la app. Los eventos de contactos y cancelaciones de suscripción son a nivel de tenant porque no están asociados con un recurso de WhatsApp. Tu endpoint debe validar la firma de YCloud antes de procesar una solicitud y devolver una respuesta exitosa 2xx a la brevedad. Consulta Configurar webhooks para obtener información sobre la validación de firmas, la gestión de entregas y directrices de seguridad. Consulta Cargas útiles de eventos de webhook para ver los esquemas de eventos.

​
Habilitar y verificar la app

Antes de utilizar la app en producción:
  1. Confirma que la app contenga los números de teléfono de WhatsApp Business previstos.
  2. Revisa cada permiso de la API y elimina el acceso que la integración no necesite.
  3. Regresa a Desarrolladores > Apps personalizadas y habilita la app desde su menú de acciones.
Lista de apps personalizadas con la acción Habilitar para una app inactiva.
  1. Confirma que el estado de la app sea Activo.
  2. Envía una solicitud de prueba con la clave de API de la app desde un entorno seguro del lado del servidor.
  3. Activa un evento seleccionado y confirma que tu endpoint lo valide y procese.
Solo las apps activas pueden autenticar solicitudes a la API o recibir eventos de webhook. Puedes buscar una app existente por su nombre o ID de app. Abre Editar para revisar o actualizar su configuración.