Notifications

The notification system provides multi-channel notifications (push, in-app, email, SMS, chat) powered by Novu. All notification endpoints are available through the KrakenD API gateway.

Concepts

Term	Description
Channel	Delivery method: `PUSH`, `IN_APP`, `EMAIL`, `SMS`, `CHAT`
Subscriber	A user registered to receive notifications
Topic	A named group of subscribers for fan-out delivery
Workflow	A notification template defining content and delivery steps
Digest	Batching strategy that groups notifications before delivery
Provider	External service for delivery (FCM, APNS, SendGrid, Twilio, etc.)

Architecture

The NotificationGatewayService extracts authentication context from request headers (X-User-ID, X-Tenant-ID) and forwards requests to the downstream NotificationService, which owns the Novu integration.

Endpoint Paths

User-facing endpoints use /api/v1/notifications/, while admin/management endpoints use /api/v1/notifications/manage/.

Push Device Registration

Register a Device

POST /api/v1/notifications/register-push-device

{
  "fcmToken": "firebase-cloud-messaging-token",
  "platform": "IOS",
  "deviceId": "device-unique-id"
}

Field	Type	Description
`fcmToken`	string	Firebase Cloud Messaging token
`platform`	enum	`IOS`, `ANDROID`, or `WEB`
`deviceId`	string	Unique device identifier

Unregister a Device

POST /api/v1/notifications/unregister-push-device

{
  "fcmToken": "firebase-cloud-messaging-token"
}

Get Registered Channels

Check which notification channels are available for the current user.

POST /api/v1/notifications/get-registered-channels

{}

Response:

{
  "channels": [
    {"channel": "PUSH", "registered": true, "credentialCount": 2},
    {"channel": "IN_APP", "registered": true, "credentialCount": 1},
    {"channel": "EMAIL", "registered": false, "credentialCount": 0}
  ]
}

Sending Notifications

Send Immediately

POST /api/v1/notifications/manage/send

{
  "userId": "recipient-user-id",
  "channel": "PUSH",
  "category": "TRANSACTIONAL",
  "content": {
    "title": "New Message",
    "body": "You have a new coaching update",
    "data": {"screen": "conversation", "id": "conv_abc"},
    "deepLink": "socayo://conversation/conv_abc"
  },
  "idempotencyKey": "unique-key-123"
}

Response:

{
  "transactionId": "txn_abc123"
}

Field	Type	Description
`userId`	string	Recipient user ID
`channel`	enum	`PUSH`, `IN_APP`, `EMAIL`, `SMS`, `CHAT`
`category`	enum	`SYSTEM`, `TRANSACTIONAL`, `PRODUCT`, `PROMOTIONAL`
`content`	object	Notification content (title, body, data, deepLink, imageUrl)
`idempotencyKey`	string	Prevents duplicate sends

Send Scheduled

Schedule a notification for a specific time.

POST /api/v1/notifications/manage/send-scheduled

{
  "userId": "recipient-user-id",
  "channel": "PUSH",
  "category": "PRODUCT",
  "content": {
    "title": "Weekly Summary",
    "body": "Your health coaching summary is ready"
  },
  "scheduledAt": "2026-03-20T09:00:00Z",
  "timezone": "America/New_York"
}

Send Delayed

Queue a notification for delivery after a delay (1–86,400 seconds).

POST /api/v1/notifications/manage/send-delayed

{
  "userId": "recipient-user-id",
  "channel": "IN_APP",
  "category": "TRANSACTIONAL",
  "content": {
    "title": "Follow-up",
    "body": "How did your workout go?"
  },
  "delaySeconds": 3600
}

Send Bulk

Fan-out to up to 100 users in a single call.

POST /api/v1/notifications/manage/send-bulk

{
  "userIds": ["user-1", "user-2", "user-3"],
  "channel": "PUSH",
  "category": "PRODUCT",
  "content": {
    "title": "New Feature",
    "body": "Check out our latest update"
  }
}

Cancel a Notification

Cancel a pending, delayed, or scheduled notification.

POST /api/v1/notifications/manage/cancel

{
  "transactionId": "txn_abc123"
}

In-App Inbox

Get Inbox Session

Get a Novu session token and WebSocket URL for direct client access to the inbox.

POST /api/v1/notifications/get-inbox-session

{}

Response:

{
  "sessionToken": "novu-session-jwt",
  "apiUrl": "https://novu-api.internal:3000",
  "wsUrl": "https://novu-ws.internal:3002"
}

Use the session token to connect directly to the Novu WebSocket for real-time inbox updates.

Get Inbox Feed

POST /api/v1/notifications/get-inbox-feed

{
  "page": 1,
  "pageSize": 20,
  "feedIds": ["default"],
  "categories": ["TRANSACTIONAL", "PRODUCT"]
}

Response:

{
  "messages": [
    {
      "messageId": "msg_123",
      "notificationId": "notif_abc",
      "title": "New Message",
      "body": "You have a coaching update",
      "data": {"screen": "conversation"},
      "deepLink": "socayo://conversation/conv_abc",
      "status": "UNSEEN",
      "category": "TRANSACTIONAL",
      "createdAt": "2026-03-18T10:00:00Z"
    }
  ],
  "hasMore": true
}

Get Unseen Count

POST /api/v1/notifications/get-inbox-unseen-count

Response:

{
  "unseenCount": 5,
  "unreadCount": 12
}

Mark Messages

Mark a single message:

POST /api/v1/notifications/mark-inbox-message

{
  "messageId": "msg_123",
  "status": "READ"
}

Mark all messages:

POST /api/v1/notifications/mark-all-inbox-messages

{
  "status": "SEEN",
  "feedIds": ["default"]
}

Status options: SEEN, READ, UNSEEN, UNREAD.

Delete Inbox Message

POST /api/v1/notifications/delete-inbox-message

{
  "messageId": "msg_123"
}

Preferences

Users can opt in/out of notification channels and categories.

Get Preferences

POST /api/v1/notifications/get-preferences

Response:

{
  "preferences": [
    {
      "channel": "PUSH",
      "channelEnabled": true,
      "categories": {
        "TRANSACTIONAL": true,
        "PRODUCT": true,
        "PROMOTIONAL": false
      }
    }
  ]
}

Update Preferences

POST /api/v1/notifications/update-preferences

{
  "channel": "PUSH",
  "category": "PROMOTIONAL",
  "enabled": false
}

info

Notifications with category SYSTEM bypass preferences — they are always delivered regardless of user settings.

Topics

Topics enable pub/sub-style fan-out delivery. Create a topic, subscribe users, then send to all subscribers.

Create a Topic

POST /api/v1/notifications/manage/create-topic

{
  "topicKey": "weekly-updates"
}

Add/Remove Subscribers

POST /api/v1/notifications/manage/add-subscribers-to-topic

{
  "topicKey": "weekly-updates",
  "subscriberIds": ["user-1", "user-2"]
}

Up to 100 subscribers per call.

POST /api/v1/notifications/manage/remove-subscribers-from-topic

{
  "topicKey": "weekly-updates",
  "subscriberIds": ["user-1"]
}

Send to Topic

POST /api/v1/notifications/manage/send-to-topic

{
  "topicKey": "weekly-updates",
  "channel": "PUSH",
  "category": "PRODUCT",
  "content": {
    "title": "Weekly Update",
    "body": "Your weekly health summary is ready"
  },
  "excludeUserIds": ["user-admin"]
}

List Topic Subscribers

POST /api/v1/notifications/manage/list-topic-subscribers

{
  "topicKey": "weekly-updates",
  "page": 1,
  "pageSize": 50
}

Check Subscription

POST /api/v1/notifications/manage/check-topic-subscription

{
  "topicKey": "weekly-updates",
  "subscriberId": "user-1"
}

Digest / Batching

Group notifications before delivery using a digest strategy.

POST /api/v1/notifications/manage/send-with-digest

{
  "userId": "user-1",
  "channel": "EMAIL",
  "category": "PRODUCT",
  "content": {
    "title": "Activity Update",
    "body": "New activity in your coaching plan"
  },
  "digestConfig": {
    "strategy": "REGULAR",
    "windowSeconds": 3600,
    "digestKey": "coaching-updates"
  }
}

Strategy	Description
`REGULAR`	Batch events within a time window (`windowSeconds`)
`LOOK_BACK`	Check for recent events before creating a new digest
`SCHEDULED`	Deliver on a cron schedule (`cronExpression`, `timezone`)

Cancel a digest event:

POST /api/v1/notifications/manage/cancel-digest-event

{
  "transactionId": "txn_abc123"
}

Subscriber Management

Create Subscriber

POST /api/v1/notifications/manage/create-subscriber

{
  "userId": "user-1",
  "subscriberData": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+1234567890",
    "locale": "en-US",
    "timezone": "America/New_York"
  }
}

Get / Update / Delete Subscriber

POST /api/v1/notifications/manage/get-subscriber

{
  "userId": "user-1"
}

POST /api/v1/notifications/manage/update-subscriber-data

{
  "userId": "user-1",
  "subscriberData": {
    "email": "jane.updated@example.com",
    "locale": "en-GB"
  }
}

POST /api/v1/notifications/manage/delete-subscriber

{
  "userId": "user-1"
}

List Subscribers

POST /api/v1/notifications/manage/list-subscribers

{
  "page": 1,
  "pageSize": 50
}

Workflow Management

Workflows define notification templates with steps and delivery preferences.

Create Workflow

POST /api/v1/notifications/manage/create-workflow

{
  "workflow": {
    "name": "Welcome Notification",
    "description": "Sent when a user completes onboarding",
    "active": true,
    "critical": false,
    "tags": ["onboarding"],
    "steps": [
      {
        "channel": "IN_APP",
        "title": "Welcome!",
        "body": "Welcome to your health coaching journey"
      },
      {
        "channel": "PUSH",
        "title": "Welcome!",
        "body": "Tap to start your first session"
      }
    ],
    "preferenceSettings": {
      "email": true,
      "push": true,
      "inApp": true,
      "sms": false,
      "chat": false
    }
  }
}

info

Setting critical: true causes the workflow to bypass user preferences — use this only for essential system notifications.

Update / Get / List / Delete Workflow

POST /api/v1/notifications/manage/update-workflow

{
  "workflowId": "wf_abc123",
  "workflow": {
    "name": "Welcome Notification v2",
    "active": true
  }
}

POST /api/v1/notifications/manage/get-workflow
POST /api/v1/notifications/manage/list-workflows
POST /api/v1/notifications/manage/delete-workflow

Provider Configuration

Configure external delivery providers (FCM, APNS, SendGrid, etc.).

POST /api/v1/notifications/manage/configure-provider

{
  "providerType": "FCM",
  "credentials": {
    "serviceAccountJson": "{...}"
  },
  "active": true
}

Supported providers: FCM, APNS, SENDGRID, SES, TWILIO, SLACK, DISCORD.

POST /api/v1/notifications/manage/get-providers

Promotion (Dev → Prod)

Manage promotion of notification template changes from development to production.

POST /api/v1/notifications/manage/get-pending-changes
POST /api/v1/notifications/manage/promote-change
POST /api/v1/notifications/manage/promote-all-changes

Activity & Delivery Status

Get Delivery Status

Track the delivery status of a specific notification.

POST /api/v1/notifications/manage/get-delivery-status

{
  "transactionId": "txn_abc123"
}

Response:

{
  "transactionId": "txn_abc123",
  "channel": "PUSH",
  "result": "DELIVERED",
  "providerMessageId": "fcm-msg-xyz",
  "queuedAt": "2026-03-18T10:00:00Z",
  "deliveredAt": "2026-03-18T10:00:02Z"
}

Delivery Result	Description
`SENT`	Queued for delivery
`DELIVERED`	Successfully delivered
`RATE_LIMITED`	Throttled by provider
`OPTED_OUT`	User opted out of this channel/category
`NO_CHANNEL`	No registered device/channel
`INVALID_CREDENTIAL`	Expired or invalid FCM token
`CANCELLED`	Cancelled before delivery
`FAILED`	Delivery failed

Get Notification Activity

Query delivery history with filtering.

POST /api/v1/notifications/manage/get-notification-activity

{
  "channels": ["PUSH", "IN_APP"],
  "categories": ["TRANSACTIONAL"],
  "startTime": "2026-03-01T00:00:00Z",
  "endTime": "2026-03-18T23:59:59Z",
  "page": 1,
  "pageSize": 50
}

RPC Summary

User-Facing (11 RPCs)

Endpoint	Description
`register-push-device`	Register FCM token
`unregister-push-device`	Remove FCM token
`get-registered-channels`	List available channels
`get-inbox-session`	Get Novu session for WebSocket
`get-inbox-feed`	Paginated inbox messages
`get-inbox-unseen-count`	Unseen/unread counts
`mark-inbox-message`	Mark single message status
`mark-all-inbox-messages`	Bulk mark messages
`delete-inbox-message`	Delete inbox message
`get-preferences`	Get notification preferences
`update-preferences`	Update notification preferences

Admin/Management (31 RPCs)

Endpoint	Description
`manage/send`	Send immediate notification
`manage/send-scheduled`	Schedule notification
`manage/send-delayed`	Delay notification
`manage/send-bulk`	Fan-out to multiple users
`manage/cancel`	Cancel pending notification
`manage/send-to-topic`	Send to topic subscribers
`manage/send-with-digest`	Send with digest batching
`manage/cancel-digest-event`	Cancel digest event
`manage/create-topic`	Create topic
`manage/delete-topic`	Delete topic
`manage/add-subscribers-to-topic`	Add subscribers to topic
`manage/remove-subscribers-from-topic`	Remove from topic
`manage/list-topic-subscribers`	List topic subscribers
`manage/check-topic-subscription`	Check subscription
`manage/create-subscriber`	Create subscriber
`manage/get-subscriber`	Get subscriber details
`manage/update-subscriber-data`	Update subscriber data
`manage/delete-subscriber`	Delete subscriber
`manage/list-subscribers`	List subscribers
`manage/create-workflow`	Create workflow template
`manage/update-workflow`	Update workflow
`manage/get-workflow`	Get workflow details
`manage/list-workflows`	List workflows
`manage/delete-workflow`	Delete workflow
`manage/configure-provider`	Configure delivery provider
`manage/get-providers`	List active providers
`manage/get-pending-changes`	List pending promotions
`manage/promote-change`	Promote single change
`manage/promote-all-changes`	Promote all changes
`manage/get-delivery-status`	Track delivery status
`manage/get-notification-activity`	Query delivery history

Concepts​

Architecture​

Endpoint Paths​

Push Device Registration​

Register a Device​

Unregister a Device​

Get Registered Channels​

Sending Notifications​

Send Immediately​

Send Scheduled​

Send Delayed​

Send Bulk​

Cancel a Notification​

In-App Inbox​

Get Inbox Session​

Get Inbox Feed​

Get Unseen Count​

Mark Messages​

Delete Inbox Message​

Preferences​

Get Preferences​

Update Preferences​

Topics​

Create a Topic​

Add/Remove Subscribers​

Send to Topic​

List Topic Subscribers​

Check Subscription​

Digest / Batching​

Subscriber Management​

Create Subscriber​

Get / Update / Delete Subscriber​

List Subscribers​

Workflow Management​

Create Workflow​

Update / Get / List / Delete Workflow​

Provider Configuration​

Promotion (Dev → Prod)​

Activity & Delivery Status​

Get Delivery Status​

Get Notification Activity​

RPC Summary​

User-Facing (11 RPCs)​

Admin/Management (31 RPCs)​

Concepts

Architecture

Endpoint Paths

Push Device Registration

Register a Device

Unregister a Device

Get Registered Channels

Sending Notifications

Send Immediately

Send Scheduled

Send Delayed

Send Bulk

Cancel a Notification

In-App Inbox

Get Inbox Session

Get Inbox Feed

Get Unseen Count

Mark Messages

Delete Inbox Message

Preferences

Get Preferences

Update Preferences

Topics

Create a Topic

Add/Remove Subscribers

Send to Topic

List Topic Subscribers

Check Subscription

Digest / Batching

Subscriber Management

Create Subscriber

Get / Update / Delete Subscriber

List Subscribers

Workflow Management

Create Workflow

Update / Get / List / Delete Workflow

Provider Configuration

Promotion (Dev → Prod)

Activity & Delivery Status

Get Delivery Status

Get Notification Activity

RPC Summary

User-Facing (11 RPCs)

Admin/Management (31 RPCs)