Engagement Configs

O engagement config é o pilar de engagement de um Activity Generation Config. Agrupa usuários ativos em níveis de engagement ordenados (ex.: casual, core, power) com base em quanto eles usam o produto dentro de uma janela móvel.

Este recurso é somente leitura: só existem GET (lista) e GET /:id. Os engagement configs são criados e editados apenas através do fluxo do AGC — veja Criar AGC e Atualizar ciclo de vida.

O gatilho de engaged é minLifetimeActionsForEngaged — o número mínimo de ações acumuladas ao longo da vida que um usuário precisa atingir antes de ser considerado engaged (padrão de plataforma 1). Não existe o campo daysToChurned. daysToChurned (e sua forma snake_case days_to_churned) não existe neste pilar — decaimento e winback são tratados pelo pilar de ressurreição, não aqui.

Campos de resposta

Campo	Tipo	Descrição
`id`	string (uuid)	Id do engagement config.
`name`	string	Nome de exibição.
`description`	string \| null	Descrição opcional.
`sourceTable`	string	Tabela da qual os dados de engagement são lidos.
`sourceColumns`	string[] \| null	Colunas usadas para a agregação.
`dateColumn`	string	Coluna que carrega o timestamp do evento.
`activityGenerationConfigId`	string (uuid)	AGC dono (NOT NULL, 1:1).
`engagementWindowDays`	integer	Janela móvel (dias) sobre a qual o engagement é medido.
`minLifetimeActionsForEngaged`	integer	Ações mínimas ao longo da vida para ser considerado engaged. Padrão de plataforma `1`.
`countingMethod`	`event_ids` \| `active_days` \| `active_weeks`	O que é contado dentro da janela.
`isActive`	boolean	Se a config está ativa.
`updatedBy`	string \| null	Id do usuário do último editor.
`createdAt`	string (ISO 8601)	Timestamp de criação.
`updatedAt`	string (ISO 8601)	Timestamp da última atualização.
`engagementLevels`	array	Buckets de nível de engagement ordenados (veja abaixo).

`engagementLevel`

Campo	Tipo	Descrição
`id`	string (uuid)	Id do nível.
`engagementConfigId`	string (uuid)	Engagement config dono.
`statusCode`	string	Code de status de retenção emitido por este nível (ex.: `habit`).
`userRetentionStatusConfigId`	string (uuid)	Config de status de retenção do tenant resolvida.
`label`	string	Label de exibição do nível.
`minThreshold`	integer	Limite inferior inclusivo (unidades contadas) para este nível.
`maxThreshold`	integer \| null	Limite superior inclusivo; `null` significa aberto (nível mais alto).
`order`	integer	Ordem do nível dentro da escada.
`isActive`	boolean	Se o nível está ativo.
`createdAt`	string (ISO 8601)	Timestamp de criação.
`updatedAt`	string (ISO 8601)	Timestamp da última atualização.

GET /api/engagement-configs

Lista os engagement configs do tenant.

Auth: Obrigatória — permissão lifecycle-config:view

Exemplo

curl https://api.reten.ai/api/engagement-configs \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-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>',
    'x-project-id': '<project-id>',
  },
});

const engagementConfigs = response.data;

Resposta `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",
    "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

Lê um único engagement config com seus níveis de engagement.

Auth: Obrigatória — permissão lifecycle-config:view

Exemplo

curl https://api.reten.ai/api/engagement-configs/e1111111-1111-1111-1111-111111111111 \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-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>',
      'x-project-id': '<project-id>',
    },
  }
);

const engagementConfig = response.data;

Resposta `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",
  "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"
    }
  ]
}