In-App Inbox

Get Inbox Session

Get a Novu session token and WebSocket URL for real-time inbox updates.

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

{}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "socketUrl": "wss://novu-ws.yocaso.dev",
  "expiresIn": "1296000"
}

Field	Type	Description
token	string	JWT for WebSocket auth
socketUrl	string	Novu WebSocket URL
expiresIn	string	Token validity in seconds (~15 days). String type (int64 protojson convention).

Real-Time Inbox Updates

The socketUrl + token from get-inbox-session open a Socket.IO connection (Novu) that pushes inbox changes live — no polling needed for the common case. Authenticate with the session token, both as an Authorization: Bearer <token> header and as a token connect param.

The server emits these events:

Event	Fires when
notification_received	A new message arrives — refresh the feed or prepend the payload
unseen_count_changed	The unseen badge count changes
unread_count_changed	The unread count changes

Novu payloads may identify a message as either _id or messageId — accept both.

Resilience. If the socket fails to connect or drops, reconnect with exponential backoff (a handful of attempts), and while disconnected fall back to polling get-inbox-unseen-count every ~30 seconds so the badge stays roughly current. The session token expires (~15 days) — call get-inbox-session again to refresh it.

Get Inbox Feed

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

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

Pagination is 1-based. Optional filter object supports unseenOnly, unreadOnly, feedIds, and categories (plain strings).

Response:

{
  "messages": [
    {
      "messageId": "69c0df5391079c0a4596f7d3",
      "notificationId": "69c0df5291079c0a4596f79b",
      "title": "Weekly Check-in",
      "body": "Time to review your progress.",
      "data": {
        "title": "Weekly Check-in",
        "body": "Time to review your progress.",
        "deep_link": "socayo://screen?name=weekly"
      },
      "deepLink": "socayo://screen?name=weekly",
      "status": "MESSAGE_STATUS_UNSEEN",
      "createdAt": "2026-03-23T06:36:03.578Z"
    }
  ],
  "totalCount": 6,
  "page": 1,
  "pageSize": 20
}

hasMore only appears when true. Fields like category, deepLink, actions are omitted when empty.

Get Unseen Count

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

Response:

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

Counts are capped at 10. hasMoreUnseen/hasMoreUnread appear when true — display as "9+".

Mark Messages

Mark a single message:

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

{
  "messageId": "msg_123",
  "markAs": "MESSAGE_STATUS_READ"
}

Response:

{
  "messages": [
    {
      "messageId": "msg_123",
      "channel": "in_app",
      "seen": true,
      "content": "Time to review your progress.",
      "status": "sent",
      "createdAt": "2026-03-23T06:36:03.578Z",
      "lastSeenDate": "2026-03-23T10:24:35.518Z"
    }
  ]
}

Mark all messages:

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

{
  "markAs": "MESSAGE_STATUS_SEEN"
}

Response: {"updatedCount": 5}

Status options: MESSAGE_STATUS_SEEN, MESSAGE_STATUS_READ, MESSAGE_STATUS_UNSEEN, MESSAGE_STATUS_UNREAD.

Delete Inbox Message

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

{
  "messageId": "msg_123"
}

Response:

{
  "status": {
    "acknowledged": true,
    "status": "deleted"
  }
}