Saltar al contenido principal
Las apps personalizadas te permiten dar a una integración acceso a números de teléfono de WhatsApp Business y API de YCloud seleccionados. Cada app cuenta con su propia clave de API, permisos de API y configuración de webhook. Usa una app personalizada cuando quieras limitar una integración únicamente a los recursos y capacidades que necesita.

Antes de empezar

Asegúrate de que:
  • Tu cuenta utilice un plan de pago de YCloud. Las apps personalizadas no están disponibles en el plan Free.
  • Tu rol pueda acceder a Developers > Custom apps en el panel 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 ni control de código fuente.

Crear una app

  1. Inicia sesión en el panel de YCloud.
  2. Ve a Developers > Custom apps.
  3. Haz clic en Create app.
Página de Custom apps en el panel de YCloud con el botón Create app.
  1. Introduce un App name. El nombre puede tener hasta 64 caracteres.
  2. Opcional: Introduce una Description de hasta 512 caracteres para que tu equipo sepa para qué se utiliza la app.
  3. Haz clic en Create.
Cuadro de diálogo de Create app con los campos App name y Description.

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á deshabilitada 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 únicamente los números de teléfono a los que la integración deba acceder.
  1. Abre la app y selecciona Assets.
  2. Haz clic en Add phone numbers.
Sección Assets de una app personalizada con el botón Add phone numbers.
  1. Busca un número por su nombre en Business Manager, WABA ID, 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 Confirm.
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 Add phone numbers 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 ahora aparecen 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 API key & permissions. Las claves de las apps personalizadas comienzan con yc_ak_. Usa la acción de copiar para guardar la clave de forma segura y luego añade únicamente los permisos que requiera la integración.
Sección API key and permissions de una app personalizada.
  1. Selecciona API key & permissions.
  2. En API permissions, haz clic en Add permissions.
  3. Filtra por categoría o busca por nombre de permiso o ámbito.
  4. Selecciona cada permiso requerido. Por ejemplo, los permisos de contactos se dividen en ámbitos de lectura, creación o actualización, y eliminación.
  5. Haz clic en Confirm.
Cuadro de diálogo Edit permissions que muestra los ámbitos de permisos para contactos.
Envía la clave generada en el encabezado X-API-Key y úsala solo desde código de servidor de confianza. 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 verifica que la app pueda acceder al número de teléfono o a la WABA correspondiente. No todas las API de YCloud están disponibles para las apps personalizadas. Toda API que no aparezca en el selector de permisos quedará denegada para la clave de una app personalizada. Las claves de apps personalizadas tampoco pueden combinarse con el encabezado X-Managed-Account-ID. Consulta Authentication para ver las pautas sobre encabezados de solicitud y gestión de credenciales.
La sección de la 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 revoca de inmediato o permanece disponible durante un periodo de transición de una hora. Actualiza cada servicio que use la clave antes de que finalice el periodo 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 Developers > Webhooks.
  1. Selecciona Webhook.
  2. Introduce tu endpoint HTTPS público en Endpoint URL y guárdalo.
  3. Guarda de forma segura el Signing secret generado.
  4. En Added events, haz clic en Add events.
Sección Webhook con los ajustes Endpoint URL, Signing secret y Added events.
  1. Filtra por categoría o busca por nombre de evento o tipo de evento.
  2. Selecciona los eventos que debe recibir tu endpoint.
  3. Si un evento ofrece opciones de ámbito de datos, elige el ámbito que se ajuste a tu integración.
  4. Haz clic en Confirm.
Cuadro de diálogo Add webhook events 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 para cada evento puede limitar aún más la entrega a los datos atribuidos a la app. Los eventos de contactos y de cancelación de suscripción son a nivel de inquilino (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 2xx correcta con rapidez. Consulta Configurar webhooks para ver instrucciones sobre la validación de firmas, el control de entregas y la seguridad. Consulta Cargas útiles de eventos de webhook para conocer los esquemas de eventos.

Habilitar y verificar la app

Antes de usar la app en producción:
  1. Confirma que la app contenga los números de teléfono de WhatsApp Business esperados.
  2. Revisa todos los permisos de la API y elimina los accesos que la integración no necesite.
  3. Vuelve a Developers > Custom apps y habilita la app desde su menú de acciones.
Lista de apps personalizadas con la acción Enable para una app inactiva.
  1. Confirma que el estado de la app sea Active.
  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 de API o recibir eventos de webhook. Puedes buscar una app existente por su nombre o ID de app. Abre Edit para revisar o actualizar su configuración.