Subscriptions

With the Subscriptions API, you can:

• Get subscription and notification details for rooms.

• Mark a channel as read or unread.

The subscription object

A subscription is one user's view of one room: what the room is called for them, whether it is open, and how much of it they have read. A trimmed example from Get All Subscriptions:

{
  "update": [
    {
      "_id": "5ALsG3QhpJfdMpyc8",
      "rid": "GENERAL",
      "name": "general",
      "t": "c",
      "u": { "_id": "EoyAmF4mxx5HxJHJB", "username": "rocket.cat" },
      "open": true,
      "alert": true,
      "unread": 1,
      "userMentions": 1,
      "groupMentions": 0,
      "ts": "2017-11-25T15:08:17.249Z"
    }
  ],
  "remove": [],
  "success": true
}

Fields you use most often:

• rid: The ID of the room this subscription belongs to. _id identifies the subscription itself.

• unread, userMentions, groupMentions: Unread counters for this user in this room.

• alert and open: Whether the room should be highlighted and whether it is shown in the user's room list.

• t: The room type — c channel, p private group, d direct message, l livechat.

Common workflows

Build an unread indicator

1. Get all subscriptions for the authenticated user. Pass updatedSince on later calls to fetch only what changed.

2. Sum the unread and mention counters per room, or get one room's subscription by its roomId.

3. Mark the room as read when the user opens it, or mark it as unread so they come back to it.

Conventions

• Subscriptions always belong to the authenticated user — you read and update your own read state, not other users'.

• Endpoints reference rooms by roomId (the subscription's rid).

• The full field list is documented in the Subscription schema definition.