Desarrollo de una aplicación de módulo de telefonía

Este documento describe lo que un desarrollador externo necesita implementar para crear su propia aplicación de telefonía para el Marketplace de Flowlu.

Para desarrollar una aplicación, consulte el Flowlu JS SDK.

Arquitectura general de la integración

Tu aplicación actúa como un middleware entre Flowlu y el servidor de telefonía externo:

Responsabilidades de tu aplicación:

1. IU de configuración — una página de conexión que se abre dentro de Flowlu en un iframe.
2. Backend — almacena la integración (mapeo de usuario de CRM ↔ cuenta de CRM ↔ cuenta del canal externo) y los tokens OAuth.
3. Canal de salida — recibe webhooks de Flowlu y entrega eventos al servidor externo.
4. Canal de entrada — recibe notificaciones del servidor externo, transforma los datos al formato requerido y los transmite a Flowlu.

Qué se debe implementar

Campos para el registro del canal (telephony/create):

• name — el nombre de la integración específica
• ref_id — el ID de tu MiniApp
• code — debe ser el valor mini_app
• webhook_url — la URL donde el CRM enviará las solicitudes
• icon_url — una URL para el icono de la integración
• can_redirect (true/false) — la capacidad de redirigir una llamada a otro empleado
• manifest_id — ID de la ubicación de integración

Registro de la aplicación en el Marketplace y ubicación de integración

Pasos:

1. Crea una aplicación en https:///module/miniapps/cabinet.
2. En el manifiesto de la aplicación, añade la ubicación de integración "telephony service connection".
3. Completa los campos de la ubicación de integración:

Después de guardar el manifiesto de la aplicación, tu aplicación aparecerá en la lista de servicios de telefonía.

Datos de contexto del iframe

Flowlu enviará una solicitud POST con el siguiente cuerpo a la URL especificada en iframe (src):

código JavaScript

{
  "domain": ".flowlu.com",
  "language": "en",
  "placement": {
    "id": "my_channel_wizard",
    "code": "contactcenter.service.wizard"
  },
  "https": "1",
  "account": { "id": "123456" },
  "app": {
    "id": "",
    "version": "1.0.0"
  },
  "auth": {
    "expires_at": "2026-03-27 17:29:33",
    "access_token": "",
    "refresh_token": ""
  },
  "ratelimit": { "limit": "16" }
}

Tu endpoint debe:

1. Validar el payload y extraer domain, app.id, app.version, account.id, auth.*.
2. Construir la URL base del CRM: https://{domain} (o http si https=0 — solo relevante para entornos de desarrollo).
3. Identificar al usuario del CRM. Patrón recomendado — "búsqueda de dos vías":
   • Ruta rápida: busca en tu base de datos el cliente OAuth por el hash de access_token + domain + app.version. Si se encuentra, el usuario ya es conocido; no es necesario llamar a la API del CRM.
   • Ruta lenta: si no se encuentra, realiza un GET https://{domain}/api/v1/module/core/user/get con el encabezado Authorization: Bearer {access_token} y crea un registro para el usuario del CRM basado en la respuesta.
4. Guardar/actualizar tokens OAuth. La clave de unicidad es (user_id, domain, app_version). Se recomienda limpiar los tokens de versiones antiguas de la aplicación durante las actualizaciones para evitar el crecimiento excesivo de la base de datos.
5. Renderizar el formulario de configuración y devolver el HTML al cliente.

Flujo de datos bidireccional

Después de conectar la integración, el intercambio de datos ocurre en dos direcciones:

Flowlu -> tu webhook_url — el CRM envía solicitudes POST a tu servidor:

• iniciación de una llamada saliente;
• solicitud de listas de llamadas y datos de llamadas específicas;
• solicitud de la lista de empleados SIP;
• comprobación del estado de salud de la integración.

Tu aplicación -> Flowlu — tú envías solicitudes POST con eventos de llamada al endpoint del CRM (POST /external/telephony/hook/mini_app/{account_id}/{telephony_uuid}):

• inicialización de llamada (para llamadas entrantes, el CRM devuelve una decisión de enrutamiento);
• llamada conectada;
• llamada completada;
• información de grabación de llamada;
• actualización del estado de la llamada.

Los contratos detallados (formatos de solicitud/respuesta, códigos de error) se describen en las especificaciones OpenAPI:

• outgoing_hooks.yaml — solicitudes de Flowlu a tu webhook (archivo adjunto al artículo)
• incoming_events.yaml — eventos de tu aplicación a Flowlu (archivo adjunto al artículo)

Flujo de trabajo de la integración

Usuario de CRM                Flowlu                   Tu aplicación
       │                         │                            │
       │ Haz clic en "Conectar"  │                            │
       │────────────────────────>│                            │
       │                         │                            │
       │                         │  Abre iframe (POST         │
       │                         │  con datos de auth)        │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │  Receives OAuth tokens     │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  GET /api/v1/module/       │
       │                         │  core/user/get             │
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {id, name, email}         │
       │                         │───────────────────────────>│
       │                         │                            │
       │                         │  POST /api/v1/module/      │
       │                         │  telephony/telephony/create│
       │                         │<───────────────────────────│
       │                         │                            │
       │                         │  {uuid: telephony_uuid}    │
       │                         │───────────────────────────>│
       │                         │                            │
       │   Integración lista     │                            │
       │<────────────────────────│                            │
       │                         │                            │

Después de esto, el CRM comienza a enviar solicitudes a la webhook_url y tu aplicación puede enviar eventos de llamada a Flowlu.