Engagement Configs

El engagement config es el pilar de engagement de un Activity Generation Config. Agrupa usuarios activos en niveles de engagement ordenados (p. ej. casual, core, power) según cuánto usan el producto dentro de una ventana móvil.

Este recurso es de solo lectura: solo existen GET (lista) y GET /:id. Los engagement configs se crean y editan únicamente a través del flujo del AGC — ver Crear AGC y Actualizar ciclo de vida.

Campos de respuesta

Campo	Tipo	Descripción
`id`	string (uuid)	Id del engagement config.
`name`	string	Nombre visible.
`description`	string \| null	Descripción opcional.
`sourceTable`	string	Tabla desde la que se leen los datos de engagement.
`sourceColumns`	string[] \| null	Columnas usadas para la agregación.
`dateColumn`	string	Columna con el timestamp del evento.
`activityGenerationConfigId`	string (uuid)	AGC dueño (NOT NULL, 1:1).
`aggregationMethod`	`nunique` \| `count` \| `sum`	Cómo se agregan las acciones dentro de la ventana.
`engagementWindowDays`	integer	Ventana móvil (días) sobre la que se mide el engagement.
`minLifetimeActionsForEngaged`	integer	Acciones de por vida mínimas para ser considerado engaged. Default de plataforma `1`.
`countingMethod`	`event_ids` \| `active_days` \| `active_weeks`	Qué se cuenta dentro de la ventana.
`isActive`	boolean	Si la config está activa.
`updatedBy`	string \| null	Id del usuario que editó por última vez.
`createdAt`	string (ISO 8601)	Timestamp de creación.
`updatedAt`	string (ISO 8601)	Timestamp de última actualización.
`engagementLevels`	array	Buckets de nivel de engagement ordenados (ver abajo).

`engagementLevel`

Campo	Tipo	Descripción
`id`	string (uuid)	Id del nivel.
`engagementConfigId`	string (uuid)	Engagement config dueño.
`statusCode`	string	Code de estado de retención que emite este nivel (p. ej. `habit`).
`userRetentionStatusConfigId`	string (uuid)	Config de estado de retención del tenant resuelta.
`label`	string	Label visible del nivel.
`minThreshold`	integer	Cota inferior inclusiva (unidades contadas) para este nivel.
`maxThreshold`	integer \| null	Cota superior inclusiva; `null` significa abierto (nivel tope).
`order`	integer	Orden del nivel dentro de la escalera.
`isActive`	boolean	Si el nivel está activo.
`createdAt`	string (ISO 8601)	Timestamp de creación.
`updatedAt`	string (ISO 8601)	Timestamp de última actualización.

GET /api/engagement-configs

Lista los engagement configs del tenant.

Auth: Requerida — permiso lifecycle-config:view

Ejemplo

curl https://api.reten.ai/api/engagement-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

import axios from 'axios';

const response = await axios.get('https://api.reten.ai/api/engagement-configs', {
headers: {
Authorization: 'Bearer <token>',
'x-tenant-id': '<tenant-id>',
},
});

const engagementConfigs = response.data;

Respuesta `200 OK`

[
  {
    "id": "e1111111-1111-1111-1111-111111111111",
    "name": "Engagement",
    "description": "Active-day engagement ladder",
    "sourceTable": "events",
    "sourceColumns": ["user_id", "event_name"],
    "dateColumn": "occurred_at",
    "activityGenerationConfigId": "agc11111-1111-1111-1111-111111111111",
    "aggregationMethod": "count",
    "engagementWindowDays": 28,
    "minLifetimeActionsForEngaged": 1,
    "countingMethod": "active_days",
    "isActive": true,
    "updatedBy": "u1111111-1111-1111-1111-111111111111",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-20T12:30:00.000Z",
    "engagementLevels": [
      {
        "id": "l1111111-1111-1111-1111-111111111111",
        "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
        "statusCode": "casual",
        "userRetentionStatusConfigId": "rs333333-3333-3333-3333-333333333333",
        "label": "Ocasional",
        "minThreshold": 1,
        "maxThreshold": 3,
        "order": 0,
        "isActive": true,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      },
      {
        "id": "l2222222-2222-2222-2222-222222222222",
        "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
        "statusCode": "habit",
        "userRetentionStatusConfigId": "rs444444-4444-4444-4444-444444444444",
        "label": "En hábito",
        "minThreshold": 8,
        "maxThreshold": null,
        "order": 1,
        "isActive": true,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
]

GET /api/engagement-configs/:id

Lee un único engagement config con sus niveles de engagement.

Auth: Requerida — permiso lifecycle-config:view

Ejemplo

curl https://api.reten.ai/api/engagement-configs/e1111111-1111-1111-1111-111111111111 \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

import axios from 'axios';

const response = await axios.get(
'https://api.reten.ai/api/engagement-configs/e1111111-1111-1111-1111-111111111111',
{
headers: {
Authorization: 'Bearer <token>',
'x-tenant-id': '<tenant-id>',
},
}
);

const engagementConfig = response.data;

Respuesta `200 OK`

{
  "id": "e1111111-1111-1111-1111-111111111111",
  "name": "Engagement",
  "description": "Active-day engagement ladder",
  "sourceTable": "events",
  "sourceColumns": ["user_id", "event_name"],
  "dateColumn": "occurred_at",
  "activityGenerationConfigId": "agc11111-1111-1111-1111-111111111111",
  "aggregationMethod": "count",
  "engagementWindowDays": 28,
  "minLifetimeActionsForEngaged": 1,
  "countingMethod": "active_days",
  "isActive": true,
  "updatedBy": "u1111111-1111-1111-1111-111111111111",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-20T12:30:00.000Z",
  "engagementLevels": [
    {
      "id": "l2222222-2222-2222-2222-222222222222",
      "engagementConfigId": "e1111111-1111-1111-1111-111111111111",
      "statusCode": "habit",
      "userRetentionStatusConfigId": "rs444444-4444-4444-4444-444444444444",
      "label": "En hábito",
      "minThreshold": 8,
      "maxThreshold": null,
      "order": 1,
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}