Notifications - Huddle/huddle-apis GitHub Wiki

Summary

Notifications surface activity relevant to the signed-in user (comments, approvals, shares, previews, and similar events).

The current HTTP API for status, received list, single notification, and last-seen is implemented by the Babble API (Huddle.Babble.Api). Paths are rooted under /babble/ on the API host (for example https://api.huddle.net/babble/...). The user is identified from the bearer token; these routes do not put userId in the path.

Related docs: Share notification information, Activities notification. Older Atom/XML style docs are summarized under Notifications (V1).

Base paths

Use case Method Path
Unseen count & last seen GET /babble/notifications/status
Received notifications (page) GET /babble/notifications/received
One notification GET /babble/notifications/received/{notificationId}
Update last seen PUT /babble/notifications/last-seen

Example

GET /babble/notifications/status

Use Authorization: Bearer … (or your environment’s equivalent). Prefer Accept: application/json unless you rely on another negotiated format.

Get unseen notification status

Returns how many notifications are unseen for the current user and the last seen notification id, plus links (self, and an edit link for last-seen).

Query parameters

Name Type Description
isMobileStatus bool When true, last-seen state can be tracked separately for mobile vs web (see PUT last-seen). Default false.

Caching

You may send If-Modified-Since. When nothing relevant changed, the API can respond with 304 Not Modified and no body.

Example

Request

GET /babble/notifications/status HTTP/1.1
Host: api.huddle.net
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lastSeenNotification": {
    "notificationId": 172135,
    "links": [
      {
        "rel": "edit",
        "href": "https://api.huddle.net/babble/notifications/last-seen"
      }
    ]
  },
  "unseenNotificationCount": 0,
  "links": [
    {
      "rel": "self",
      "href": "https://api.huddle.net/babble/notifications/status"
    }
  ]
}

Get received notifications

Returns a page of notifications for the current user as JSON (collection with notifications, links, etc.). This is what the web UI typically loads when opening the notification bell (often with pagesize and includeNotificationSummary=true).

Query parameters

Name Type Description
pageSize int Page size (e.g. 100).
isRead bool? Filter by read state when supported.
notifiableEventTypes string Filter by event types.
huddleObjectType string Filter by object type.
orderBy string Sort field (e.g. created date).
direction string Paging direction (e.g. forwards).
maxOrderByValue string Key-set paging cursor (value).
maxOrderById int? Key-set paging cursor (id).
includeNotificationSummary bool? When true, responses include summary-friendly fields for list rendering.

Caching

If-Modified-Since may yield 304 Not Modified when appropriate.

Example

Request

GET /babble/notifications/received?pagesize=100&includeNotificationSummary=true HTTP/1.1
Host: api.huddle.net
Accept: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response (shape)

{
  "id": "urn:uuid:…",
  "links": [
    {
      "href": "https://api.huddle.net/babble/notifications/received",
      "rel": "self"
    }
  ],
  "notifications": [
    {
      "action": "DocumentApprovalUpdated",
      "content": "",
      "id": "134138",
      "links": [
        {
          "href": "https://api.huddle.net/files/documents/742681",
          "rel": "alternate"
        }
      ],
      "publishedDate": "Fri, 26 Jul 2024 06:48:15 GMT",
      "recipients": [
        {
          "email": "[email protected]",
          "name": "Example User",
          "links": [
            { "href": "https://api.huddle.net/users/921355", "rel": "self" },
            { "href": "https://api.huddle.net/files/users/921355/avatar?h=…", "rel": "avatar", "type": "image/jpeg" }
          ]
        }
      ],
      "recipientsCount": 1,
      "sender": {
        "email": "[email protected]",
        "name": "Example User",
        "links": [
          { "href": "https://api.huddle.net/users/921355", "rel": "self" },
          { "href": "https://api.huddle.net/files/users/921355/avatar?h=…", "rel": "avatar", "type": "image/jpeg" }
        ]
      },
      "title": "Huddle apps for desktop and mobile",
      "workspace": {
        "title": "Your first workspace",
        "links": [
          { "href": "https://api.huddle.net/workspaces/921357", "rel": "self" }
        ]
      }
    }
  ],
  "title": ""
}

action, optional content, and link sets vary by notification type. Paging links (first, next, etc.) appear when the server returns additional pages.

Get one notification

GET /babble/notifications/received/{notificationId} HTTP/1.1
Authorization: Bearer …

Invalid or non-positive notificationId yields 400 Bad Request.

Set last seen notification

Marks how far the user has read the stream. Use PUT to notifications/last-seen with a JSON body. The server updates unseen counts and last-seen pointers; web vs mobile can be separated using isMobileStatus (must align with how you call GET …/status).

Request body

Field Type Description
notificationId int Id of the newest notification the user has seen (same id as in the received list / status payload).
isMobileStatus bool true when updating mobile last-seen; false for web.

Example

Request

PUT /babble/notifications/last-seen HTTP/1.1
Host: api.huddle.net
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "notificationId": 172135,
  "isMobileStatus": false
}

Response

204 No Content on success (no response body).

Mobile host paths (/mobile/notifications/...)

Some clients still call the API host with the user id in the path (these are not the same URLs as …/babble/notifications/… above):

Operation Example
Received list GET https://api.huddle.net/mobile/notifications/user/{userId}/received
Last-seen status / update surface GET / PUT https://api.huddle.net/mobile/notifications/user/{userId}/received/last-seen

Responses may include links such as rel="alternate" pointing at legacy-style paths (for example notifications/user/-1/received). Treat these as compatibility links; prefer Babble paths under /babble/ for new work.

Example: GET /mobile/notifications/user/{userId}/received/last-seen

{
  "unseenCount": 4,
  "links": [
    {
      "rel": "self",
      "href": "https://api.huddle.net/mobile/notifications/user/921355/received/last-seen"
    },
    {
      "rel": "alternate",
      "title": "Received Notifications",
      "href": "https://api.huddle.net/notifications/user/-1/received"
    }
  ]
}