Notifications & Badges

Chat notifications inform users about unread messages and mentions across their conversations. Badge counts provide an aggregated view of unread state for rendering UI indicators. Muted conversations do not generate notifications. Badges are derived state computed from conversation activity.

The notification model

Each notification represents a notable chat event that requires the user's attention.

Properties

Name
id
Type
string
Description
Unique UUID identifier for the notification.
Name
type
Type
string
Description
Notification type: unread (new message in conversation) or mention (user was @-mentioned).
Name
conversation_id
Type
string
Description
UUID of the conversation that triggered the notification.
Name
conversation_name
Type
string
Description
Display name of the conversation.
Name
source_event_id
Type
string
Description
The Matrix event ID that triggered this notification.
Name
is_read
Type
boolean
Description
Whether the notification has been read by the user.
Name
metadata
Type
object
Description
Additional context about the notification. Contains sender_name (the name of the user who triggered it).
Name
created_at
Type
timestamp
Description
ISO 8601 timestamp of when the notification was created.

GET/chat/api/v1/notifications

List notifications

Retrieve a paginated list of notifications for the authenticated user, ordered by most recent first. Notifications are generated for unread messages and mentions in non-muted conversations.

Optional attributes

Name
type
Type
string
Description
Filter by notification type: unread or mention.
Name
is_read
Type
boolean
Description
Filter by read state: true for read notifications, false for unread.
Name
cursor
Type
string
Description
Cursor for pagination.
Name
limit
Type
integer
Description
Number of notifications to return per page. Default is 50.

Request

GET

/chat/api/v1/notifications

curl -G https://your-sphere.example.com/chat/api/v1/notifications \
  -H "Authorization: Bearer {token}" \
  -d is_read=false \
  -d limit=20

Response

{
  "data": [
    {
      "id": "notif-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "type": "mention",
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "conversation_name": "Engineering Team",
      "source_event_id": "$evt_abc123:your-sphere.example.com",
      "is_read": false,
      "metadata": {
        "sender_name": "Alice Martin"
      },
      "created_at": "2026-02-24T14:35:00Z"
    },
    {
      "id": "notif-2b3c4d5e-6f7a-8901-bcde-f12345678901",
      "type": "unread",
      "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "conversation_name": "Bob Johnson",
      "source_event_id": "$evt_def456:your-sphere.example.com",
      "is_read": false,
      "metadata": {
        "sender_name": "Bob Johnson"
      },
      "created_at": "2026-02-24T14:20:00Z"
    }
  ]
}

GET/chat/api/v1/notifications/{id}

Get notification

Retrieve the details of a specific notification by its UUID.

URL parameters

Name
id
Type
string
Description
The UUID of the notification to retrieve.

Request

GET

/chat/api/v1/notifications/{id}

curl https://your-sphere.example.com/chat/api/v1/notifications/notif-1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "notif-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "type": "mention",
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "conversation_name": "Engineering Team",
    "source_event_id": "$evt_abc123:your-sphere.example.com",
    "is_read": false,
    "metadata": {
      "sender_name": "Alice Martin"
    },
    "created_at": "2026-02-24T14:35:00Z"
  }
}

POST/chat/api/v1/notifications/{id}/read

Mark notification as read

Mark a single notification as read. Once marked, the notification will no longer contribute to unread badge counts.

URL parameters

Name
id
Type
string
Description
The UUID of the notification to mark as read.

Request

POST

/chat/api/v1/notifications/{id}/read

curl -X POST https://your-sphere.example.com/chat/api/v1/notifications/notif-1a2b3c4d-5e6f-7890-abcd-ef1234567890/read \
  -H "Authorization: Bearer {token}"

Response (200)

{
  "message": "Notification marked as read."
}

POST/chat/api/v1/notifications/bulk-read

Bulk mark as read

Mark multiple notifications as read in a single request. You can provide a list of specific notification IDs, or set all to true to mark every unread notification as read.

Optional attributes

Name
ids
Type
array
Description
Array of notification UUIDs to mark as read. Mutually exclusive with all.
Name
all
Type
boolean
Description
Set to true to mark all unread notifications as read. Mutually exclusive with ids.

Request

POST

/chat/api/v1/notifications/bulk-read

curl -X POST https://your-sphere.example.com/chat/api/v1/notifications/bulk-read \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

Response (200)

{
  "message": "All notifications marked as read."
}

GET/chat/api/v1/badges

Get badge counts

Retrieve aggregated badge counts for the authenticated user. Returns total unread messages and mentions across all non-muted conversations, along with per-conversation breakdowns. Badge counts are derived state -- muted conversations are excluded.

The response includes a cache_ttl_seconds field indicating how long the client should cache the values before re-fetching.

Request

GET

/chat/api/v1/badges

curl https://your-sphere.example.com/chat/api/v1/badges \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "total_unread": 5,
    "total_mentions": 2,
    "calculated_at": "2026-02-24T14:36:00Z",
    "cache_ttl_seconds": 30,
    "by_conversation": {
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
        "unread": 3,
        "mentions": 1
      },
      "b2c3d4e5-f6a7-8901-bcde-f12345678901": {
        "unread": 2,
        "mentions": 1
      }
    }
  }
}