Notification configs

This module stores the text and switches for trainee push notifications at three levels:

Platform defaults. One NotificationTypeConfig row per type, edited by Perform admins.
Studio overrides. One StudioNotificationConfig row per studio and type, edited by the studio owner or head coach. An override replaces the default for that studio.
Trainee preferences. A list of muted groups on Client.mutedNotificationGroups, edited by the trainee in the app.

It does not send anything. Other modules read these settings when they send a push. Source: backend/apps/core-api/src/modules/notification-configs/ (routes, controller, service, repository, schema) and backend/apps/core-api/src/lib/notification-messages.ts for the message helpers and the normalizer.

Mounting and auth

Router	Base path	Middleware	Who
`notificationConfigsAdminRouter`	`/v1/admin/notification-configs`	`serviceAuth` only	A signed service call. No user context, no `req.auth`
`notificationConfigsWebRouter`	`/v1/web/notification-configs`	Web lane	Any role to read. `OWNER` or `HEAD_COACH` to write
`notificationSettingsWebRouter`	`/v1/web/studio/notification-settings`	Web lane	Any role to read. `OWNER` or `HEAD_COACH` to write
`notificationConfigsReadRouter`	`/v1/trainee/notification-configs`	`authenticateTrainee` inside the router	A trainee
`notificationPreferencesRouter`	`/v1/trainee/notification-preferences`	`authenticateTrainee` inside the router	A trainee

The web lane is serviceAuth, webUserContext, webLimiter. Write routes add requireRole(StudioRole.OWNER, StudioRole.HEAD_COACH), which throws FORBIDDEN (403) with insufficient role for anyone else. See API overview. authenticateTrainee (middleware/trainee-auth.ts) expects Authorization: Bearer <trainee token> and verifies it with BETTER_AUTH_SECRET. It rejects with UNAUTHORIZED (401) when the token is missing or invalid, or when the studio no longer exists. A preview session can only make GET requests. Any other method gets FORBIDDEN (403) with details.reason PREVIEW_READ_ONLY. These two trainee routers do not apply requireTraineeAppAccess, so a trainee whose app access is paused can still call them.

Notification types

notificationConfigType in the schema lists 15 values. Twelve are active (ACTIVE_NOTIFICATION_TYPES). The other three are retired: they stay in the enum and have defaults, but every list endpoint filters them out.

Active types

Type	Category	Kind	Variables	Opens	Throttle	Max messages	On by default
`REST_TIMER`	workout	single	`exercise`	none	none	1	yes
`WORKOUT_IDLE`	workout	single	none	`activeWorkout`	none	1	yes
`WORKOUT_UNFINISHED`	workout	single	none	`activeWorkout`	none	1	yes
`FORM_SENT`	forms	formSent	`form`	`form`	none	3	yes
`FORM_REMINDERS`	forms	formReminders	`form`	per message	none	10	yes
`TRAINING_PLAN_ASSIGNED`	plans	single	`plan`	`training`	none	1	yes
`TRAINING_PLAN_UPDATED`	plans	single	`plan`	`training`	6 hours	1	yes
`NUTRITION_PLAN_ASSIGNED`	plans	single	`plan`	`nutrition`	none	1	no
`NUTRITION_PLAN_UPDATED`	plans	single	`plan`	`nutrition`	6 hours	1	yes
`SUBSCRIPTION_RENEWED`	subscription	single	`plan`, `studio`	`profile`	none	1	no
`SUBSCRIPTION_FROZEN`	subscription	single	`studio`	`subscription`	none	1	no
`TRAINER_MESSAGE`	messages	single	`trainer`, `message`	none	none	1	yes

These columns come from NOTIFICATION_CATALOGUE and NOTIFICATION_CONFIG_DEFAULTS. Variables are written in templates as {{name}}. The 6 hour throttle is PLAN_UPDATE_THROTTLE_HOURS. The default title and body texts are in Hebrew and live in NOTIFICATION_CONFIG_DEFAULTS. The categories, in order, are workout, forms, plans, subscription, messages (NOTIFICATION_CATEGORIES).

Retired types

FORM_ASSIGNED, CHECK_IN_DUE and CHECK_IN_TOMORROW are not in ACTIVE_NOTIFICATION_TYPES.

Kinds and messages

Every setting is exposed as a list of messages (notificationMessage in the schema).

Field	Type	Used by
`id`	string, 1 to 40 chars	all
`enabled`	boolean	all
`title`	string, up to 300 chars	all
`subtitle`	string, up to 1500 chars	all
`formType`	`ALL`, `INTAKE` or `CHECK_IN`	`formSent`, `formReminders`
`offsetDays`	integer	`formReminders`
`time`	`HH:MM` string	`formReminders`
`onlyIfNotFilled`	boolean	`formReminders`
`opens`	`home` or `form`	`formReminders`

single. One message with the fixed id default. It is built from the row’s titleTemplate and bodyTemplate. The stored messages column is not used.
formSent. Up to 3 messages, each for a form type. pickFormSentMessage picks the enabled message whose formType matches the form, and falls back to the enabled ALL message. The defaults are one CHECK_IN message and one ALL message.
formReminders. Up to 10 reminders, each with a day offset from the form’s day and a time. The default is one reminder the day before a check-in at 19:00 that opens the home screen.

For the two multi-message kinds, messagesOf reads the stored messages JSON. When it is missing, empty or does not parse, the type’s default messages are used.

Preference groups

A trainee mutes groups, not types. notificationPreferenceGroup has six values, in this order:

Group	Types
`CHECK_INS`	`FORM_SENT` and `FORM_REMINDERS` messages for check-in forms
`FORMS`	`FORM_SENT` and `FORM_REMINDERS` messages for other forms
`PLANS`	`TRAINING_PLAN_ASSIGNED`, `TRAINING_PLAN_UPDATED`, `NUTRITION_PLAN_ASSIGNED`, `NUTRITION_PLAN_UPDATED`
`WORKOUT_REMINDERS`	`REST_TIMER`, `WORKOUT_IDLE`, `WORKOUT_UNFINISHED`
`COACH_MESSAGES`	`TRAINER_MESSAGE`
`SUBSCRIPTION`	`SUBSCRIPTION_RENEWED`, `SUBSCRIPTION_FROZEN`

COACH_MESSAGES is locked (LOCKED_NOTIFICATION_GROUPS). A trainee cannot switch it off, and isNotificationMuted ignores it even if it somehow lands in the muted list. notificationGroupFor(type, formType) decides the group. For FORM_SENT and FORM_REMINDERS the form type decides: CHECK_IN maps to CHECK_INS, anything else, including no form type, maps to FORMS. Every other type uses the fixed NOTIFICATION_TYPE_GROUPS map.

Platform defaults (admin)

Both admin endpoints first call ensureDefaults, which upserts a default row for each of the 12 active types. Existing rows are left untouched.

`GET /v1/admin/notification-configs`

Lists the platform default row for every active type, sorted by type. Auth: serviceAuth only. Response: 200 with an array of NotificationTypeConfig rows.

{
  "ok": true,
  "data": [
    {
      "id": "cmb6c1d2e000fabcd1234efgh",
      "type": "TRAINING_PLAN_UPDATED",
      "enabled": true,
      "titleTemplate": "Your plan was changed",
      "bodyTemplate": "Your training plan was updated",
      "sound": true,
      "sendTime": null,
      "messages": null,
      "createdAt": "2026-09-01T00:00:00.000Z",
      "updatedAt": "2026-09-01T00:00:00.000Z"
    }
  ],
  "requestId": "req_123"
}

`PATCH /v1/admin/notification-configs/:type`

Updates one platform default. Auth: serviceAuth only.

string

required

Any of the 15 notificationConfigType values.

boolean

Master switch for the type.

string

At least 1 character.

string

May be empty.

boolean

Whether the push plays a sound.

string

HH:MM, 24 hour.

Only the fields sent are changed. For FORM_SENT and FORM_REMINDERS, the service also rewrites the first stored message so the two representations agree: its title takes titleTemplate, its subtitle takes bodyTemplate, and its time takes sendTime when that message already has a time. Response: 200 with the updated row, in the same shape as the list. Errors:

Code	Status	When
`VALIDATION`	422	Unknown `type`, or the body fails the schema
`NOT_FOUND`	404	A retired type that has no row. `ensureDefaults` only creates rows for active types, so the update hits a missing row

Studio overrides, flat shape (web)

These two endpoints expose one flat row per type. They predate the multi-message settings and stay for callers that only need title, body and time.

`GET /v1/web/notification-configs`

Lists the effective config for each active type in the caller’s studio. Auth: web lane, any role. For each active type the studio override is returned when one exists, otherwise the platform default. customized says which one it is. Response: 200.

{
  "ok": true,
  "data": [
    {
      "type": "TRAINER_MESSAGE",
      "enabled": true,
      "titleTemplate": "A message from your coach",
      "bodyTemplate": "{{message}}",
      "sound": true,
      "sendTime": null,
      "messages": null,
      "customized": false
    }
  ],
  "requestId": "req_123"
}

`PATCH /v1/web/notification-configs/:type`

Creates or updates the studio’s override for one type. Auth: web lane, roles OWNER or HEAD_COACH.

string

required

A notificationConfigType value.

boolean

Switch for this studio.

string

At least 1 character.

string

May be empty.

boolean

Whether the push plays a sound.

string

HH:MM, 24 hour.

The service starts from the studio’s current effective values, applies the fields sent, and upserts the StudioNotificationConfig row. A studio’s first PATCH therefore copies every other field from the platform default into the override. Later changes to the platform default no longer reach that studio for that type. For the multi-message kinds, the first message is rewritten the same way as in the admin PATCH. Response: 200.

{
  "ok": true,
  "data": {
    "type": "TRAINER_MESSAGE",
    "enabled": true,
    "titleTemplate": "New message from the studio",
    "bodyTemplate": "{{message}}",
    "sound": false,
    "sendTime": null,
    "customized": true
  },
  "requestId": "req_123"
}

messages is included only for FORM_SENT and FORM_REMINDERS. Errors: VALIDATION (422), FORBIDDEN (403) insufficient role, UNAUTHORIZED (401). The route accepts retired types too. For one of those the service writes an override built from the code defaults, but no list endpoint ever returns it.

Studio settings, structured shape (web)

This is the shape the notification settings screen uses. Each setting carries its catalogue metadata, its messages and the platform defaults to reset to.

`GET /v1/web/studio/notification-settings`

Returns every active type with its messages, plus the category order. Auth: web lane, any role. Response: 200. Settings come in ACTIVE_NOTIFICATION_TYPES order.

{
  "ok": true,
  "data": {
    "categories": ["workout", "forms", "plans", "subscription", "messages"],
    "settings": [
      {
        "type": "FORM_REMINDERS",
        "category": "forms",
        "kind": "formReminders",
        "variables": ["form"],
        "opens": null,
        "throttleHours": null,
        "maxMessages": 10,
        "enabled": true,
        "sound": true,
        "messages": [
          {
            "id": "reminder-1",
            "enabled": true,
            "formType": "CHECK_IN",
            "offsetDays": -1,
            "time": "19:00",
            "onlyIfNotFilled": false,
            "opens": "home",
            "title": "Your check-in day is coming up",
            "subtitle": "Tomorrow is your check-in day."
          }
        ],
        "customized": false,
        "defaults": {
          "enabled": true,
          "sound": true,
          "messages": [
            {
              "id": "reminder-1",
              "enabled": true,
              "formType": "CHECK_IN",
              "offsetDays": -1,
              "time": "19:00",
              "onlyIfNotFilled": false,
              "opens": "home",
              "title": "Your check-in day is coming up",
              "subtitle": "Tomorrow is your check-in day."
            }
          ]
        }
      }
    ]
  },
  "requestId": "req_123"
}

enabled, sound and messages are the studio’s effective values. defaults always reflects the platform row.

`PUT /v1/web/studio/notification-settings/:type`

Replaces the studio’s whole setting for one type. Auth: web lane, roles OWNER or HEAD_COACH.

string

required

Must be an active type.

boolean

required

Switch for the whole type in this studio.

boolean

required

Whether the push plays a sound.

object[]

required

1 to 20 messages in the notificationMessage shape described above. The per-type limit is checked after parsing.

normalizeSetting cleans and checks the messages:

title has line breaks collapsed to a space and is trimmed. It must not be empty.
subtitle is trimmed.
Message ids must be unique.
single: the message id becomes default and the message is always enabled. Extra fields are dropped.
formSent: formType defaults to ALL. Only id, enabled, title, subtitle and formType are kept.
formReminders: formType defaults to CHECK_IN. offsetDays is required and must be between -3 and 3. A negative offset (before the form’s day) is only allowed for CHECK_IN. time is required and must be HH:MM. onlyIfNotFilled is forced to false for a negative offset and defaults to true otherwise. opens defaults to form. Reminders are sorted by offsetDays, then time.

The stored override keeps titleTemplate, bodyTemplate and sendTime in step with the first message. messages is stored only for the multi-message kinds. Response: 200 with the normalized setting.

{
  "ok": true,
  "data": {
    "type": "FORM_SENT",
    "enabled": true,
    "sound": true,
    "messages": [
      {
        "id": "form-all",
        "title": "A new form is waiting",
        "subtitle": "{{form}} is waiting for you",
        "enabled": true,
        "formType": "ALL"
      }
    ],
    "customized": true
  },
  "requestId": "req_123"
}

Errors:

Code	Status	When
`VALIDATION`	422	Zod rejects the path or body. `details` is the list of Zod issues
`VALIDATION`	422	`invalid notification setting`. `details.issues` is a list of `{ path, code }`
`NOT_FOUND`	404	`notification type not found` (a retired type)
`FORBIDDEN`	403	`insufficient role`

Issue codes from the normalizer:

`code`	`path`	Meaning
`tooManyMessages`	`messages`	More messages than the type’s `maxMessages`
`duplicateId`	`messages.N.id`	Two messages share an id
`titleRequired`	`messages.N.title`	Title is empty after cleaning
`offsetOutOfRange`	`messages.N.offsetDays`	Missing, or outside -3 to 3
`beforeOnlyForCheckIn`	`messages.N.offsetDays`	Negative offset on a non check-in reminder
`timeInvalid`	`messages.N.time`	Missing, or not `HH:MM`

There is no endpoint to delete an override. To go back to the platform text, send the values from defaults. The setting stays customized: true.

Trainee endpoints

`GET /v1/trainee/notification-configs`

Returns the effective config per active type for the trainee’s studio, with the trainee’s mutes applied. The app uses it for notifications it schedules on the device. Auth: trainee bearer token. enabled is the studio’s switch and not muted by the trainee. The mute check here calls isNotificationMuted(type, muted) with no form type, so both FORM_SENT and FORM_REMINDERS follow the FORMS group in this list. Response: 200.

{
  "ok": true,
  "data": [
    {
      "type": "REST_TIMER",
      "enabled": true,
      "titleTemplate": "Rest is over. Time for the next set",
      "bodyTemplate": "",
      "sound": true,
      "sendTime": null
    }
  ],
  "requestId": "req_123"
}

messages and customized are not included. Errors: UNAUTHORIZED (401), NOT_FOUND (404) trainee not found.

`GET /v1/trainee/notification-preferences`

Lists the groups the trainee can control. Auth: trainee bearer token. A group is listed only when at least one enabled type in the studio feeds it:

A single-kind type adds its fixed group.
A multi-message type adds a group per enabled message. A message with formType ALL, or none, adds both FORMS and CHECK_INS. CHECK_IN adds CHECK_INS. INTAKE adds FORMS.

Groups come back in enum order. A locked group is always reported as enabled. Response: 200.

{
  "ok": true,
  "data": {
    "groups": [
      { "key": "CHECK_INS", "locked": false, "enabled": true },
      { "key": "FORMS", "locked": false, "enabled": true },
      { "key": "PLANS", "locked": false, "enabled": false },
      { "key": "WORKOUT_REMINDERS", "locked": false, "enabled": true },
      { "key": "COACH_MESSAGES", "locked": true, "enabled": true }
    ]
  },
  "requestId": "req_123"
}

Errors: UNAUTHORIZED (401), NOT_FOUND (404) trainee not found.

`PATCH /v1/trainee/notification-preferences`

Switches one group on or off for the trainee. Auth: trainee bearer token. Refused for preview sessions.

string

required

One of CHECK_INS, FORMS, PLANS, WORKOUT_REMINDERS, COACH_MESSAGES, SUBSCRIPTION.

boolean

required

false adds the group to Client.mutedNotificationGroups. true removes it.

A group can be muted even when it is not currently listed for the studio. Response: 200 with the same shape as the GET, after the change. Errors:

Code	Status	When
`VALIDATION`	422	Unknown group or bad body
`VALIDATION`	422	`this notification cannot be switched off` (a locked group with `enabled: false`)
`NOT_FOUND`	404	`trainee not found`
`FORBIDDEN`	403	Preview session, `details.reason` is `PREVIEW_READ_ONLY`
`UNAUTHORIZED`	401	Missing or invalid token

Forms for the form types that FORM_SENT and FORM_REMINDERS messages target.
Coach assistant sends TRAINER_MESSAGE pushes and respects the studio switch.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Notification configs

Mounting and auth

Notification types

Active types

Retired types

Kinds and messages

Preference groups

Platform defaults (admin)

`GET /v1/admin/notification-configs`

`PATCH /v1/admin/notification-configs/:type`

Studio overrides, flat shape (web)

`GET /v1/web/notification-configs`

`PATCH /v1/web/notification-configs/:type`

Studio settings, structured shape (web)

`GET /v1/web/studio/notification-settings`

`PUT /v1/web/studio/notification-settings/:type`

Trainee endpoints

`GET /v1/trainee/notification-configs`

`GET /v1/trainee/notification-preferences`

`PATCH /v1/trainee/notification-preferences`

​Mounting and auth

​Notification types

​Active types

​Retired types

​Kinds and messages

​Preference groups

​Platform defaults (admin)

​GET /v1/admin/notification-configs

​PATCH /v1/admin/notification-configs/:type

​Studio overrides, flat shape (web)

​GET /v1/web/notification-configs

​PATCH /v1/web/notification-configs/:type

​Studio settings, structured shape (web)

​GET /v1/web/studio/notification-settings

​PUT /v1/web/studio/notification-settings/:type

​Trainee endpoints

​GET /v1/trainee/notification-configs

​GET /v1/trainee/notification-preferences

​PATCH /v1/trainee/notification-preferences

​Related pages

Mounting and auth

Notification types

Active types

Retired types

Kinds and messages

Preference groups

Platform defaults (admin)

`GET /v1/admin/notification-configs`

`PATCH /v1/admin/notification-configs/:type`

Studio overrides, flat shape (web)

`GET /v1/web/notification-configs`

`PATCH /v1/web/notification-configs/:type`

Studio settings, structured shape (web)

`GET /v1/web/studio/notification-settings`

`PUT /v1/web/studio/notification-settings/:type`

Trainee endpoints

`GET /v1/trainee/notification-configs`

`GET /v1/trainee/notification-preferences`

`PATCH /v1/trainee/notification-preferences`

Related pages