# Message Marks

A message mark is a fact one user records about one message, once. The built-in type is `played`: a recipient played a voice note or a video. Marks are per message and per user, a user cannot remove one, and the message author sees who marked their message. They are separate from [reactions](https://getstream.io/chat/docs/ruby/send-reaction/) and from the per-channel [read and delivered receipts](https://getstream.io/chat/docs/ruby/message-delivery-and-read-status/).

>
> **Info:** Marks are off by default. Stream enables them per app, it is not a setting you can turn on yourself. [Contact support](https://getstream.io/contact/support/) to enable them for your app.
>

>
> **Info:** The server-side SDKs do not have methods for marks yet. The server-side examples on this page use the REST API with cURL. The JavaScript client example needs the SDK release that adds `sendMessageMark`.
>

## How marks are turned on

Three things decide whether a message can be marked:

1. Stream has enabled marks for your app.
2. The channel type lists the mark type in `mark_types`.
3. The type's policy admits the message and the channel: the message has an attachment the type requires, and the channel has no more members than the type allows.

The built-in `played` type needs no setup beyond the first two. It applies to messages with an attachment of type `audio`, `voiceRecording` or `video`. An [app-level policy](#app-level-policy) can define your own types, change which attachments qualify, lower the member limit and tie marks to users' read-receipt settings.

## Enabling marks on a channel type

Set `mark_types` on the channel type from the server side. An empty list turns marks off for that channel type. A type can be listed only once, and it must be a built-in type or one your app policy defines, otherwise the call fails with a `400` that names the type.

```bash
curl -X PUT "https://chat.stream-io-api.com/channeltypes/messaging?api_key=${API_KEY}" \
  -H "Authorization: ${SERVER_TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{ "mark_types": ["played"] }'
```

A member's `own_capabilities` on a channel contains `send-message-mark` when the current user can mark messages in it: marks are enabled for the app, the channel type lists a type that admits the channel's size, and the user has the `CreateMessageMark` permission. Channel members have the permission by default on the built-in channel types.

A type admits a channel's size only when the channel's member count is known and at most the type's `max_members`. A channel whose `member_count` reads 0, because it has no members or its counter has not been repaired, refuses marks with error code `19`, and the capability is absent there too.

## App-level policy

The app settings carry an optional `message_marks` policy that says what each mark type is. The channel type's `mark_types` says where it is on. Define a custom type in the policy first, then list it on the channel type.

Send the policy with the app settings endpoint. The object replaces the stored policy as a whole: send every type you want to keep, send `null` to clear it, and leave the field out to keep it unchanged. Without a policy, `played` runs on its defaults.

```bash
curl -X PATCH "https://chat.stream-io-api.com/app?api_key=${API_KEY}" \
  -H "Authorization: ${SERVER_TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "message_marks": {
      "types": {
        "played": { "requires": ["audio", "voiceRecording", "video", "acme.voice"] },
        "acme.viewed": { "requires": ["image", "video"], "max_members": 50 }
      },
      "privacy": { "respect_read_receipts": true }
    }
  }'
```

The fields:

- `types`: one entry per mark type, at most 20. A built-in name such as `played` overrides its defaults.
- Custom type names must be namespaced and lowercase, for example `acme.viewed`: segments of letters, digits and `_` that start with a letter, joined by `.`, at most 32 characters. The names `read`, `unread`, `delivered`, `sent`, `seen` and `failed` are reserved.
- `types.<name>.requires`: the attachment `type` values that qualify a message, any one of them. 1 to 10 entries, each up to 64 characters of letters, digits, `_`, `.` and `-`, with no duplicates. Custom attachment types work. A custom mark type must list at least one. For a built-in type the list replaces the default, so a list without `video` turns video off for `played`, and leaving the list out keeps the default.
- `types.<name>.max_members`: the channel size above which the type is off, 1 to 100. Defaults to 100.
- `privacy.respect_read_receipts`: when `true`, a mark by a user whose [read receipts are off](https://getstream.io/chat/docs/ruby/message-delivery-and-read-status/#read-receipts) is kept for that user only. See [Privacy and shadow bans](#privacy-and-shadow-bans). Defaults to `false`.

A policy that fails validation is a `400` that names the field, and the stored policy stays as it was. Removing a type from the policy turns it off wherever it is listed. Its marks stay stored and show again if you define the type again.

## Marking a message

Send a mark with `POST /messages/{id}/marks`. The body has the mark `type`. Server-side calls also pass the `user_id` of the user who played the message. The call is idempotent:

- The first call for a user, message and type writes the mark and returns `created: true`.
- Every later call for the same user, message and type returns `created: false` and does nothing else. The `mark` in that response is the stored mark, with its original `created_at`.
- A mark by the message author on their own message is accepted and returns `created: false`. Nothing is written and no event is sent. The author still needs to be a member of the channel, and the message still needs a qualifying attachment.
- A message from a shadow-banned author is marked like any other, and the mark is stored hidden: the first call returns `created: true`, a repeat returns `created: false` with the stored time, the user gets the event and finds the mark in `own_marks`, and the author never does. See [Privacy and shadow bans](#privacy-and-shadow-bans).
- A message the user deleted for themselves answers like a first write: `created: true` and a mark stamped with the current time. Nothing is stored and no event is sent, so a repeat call on such a message answers `created: true` again.

Like every POST, a successful call returns `201`.

```js label="JavaScript (client)"
// The current user played the voice note.
const { mark, created } = await channel.sendMessageMark(
  { id: messageId },
  { type: "played" },
);
```

```bash label="cURL (server)"
curl -X POST "https://chat.stream-io-api.com/messages/${MESSAGE_ID}/marks?api_key=${API_KEY}" \
  -H "Authorization: ${SERVER_TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{ "type": "played", "user_id": "listener-id" }'
```

The response carries the mark and whether this call wrote it:

```json
{
  "mark": {
    "type": "played",
    "message_id": "voice-note-1",
    "user_id": "listener-id",
    "created_at": "2026-11-06T10:00:00.000Z"
  },
  "created": true,
  "duration": "3.10ms"
}
```

A repeat call returns the same shape with `created: false` and the `created_at` of the stored mark.

### Errors

| Status                                                 | When                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`, error code `19` (channel feature not supported) | Marks are not enabled for the app, the channel type does not list the type, the channel has more members than the type allows, or the channel's member count is 0. Clients can cache this answer per channel.                                                                   |
| `400`                                                  | The `type` is missing, malformed, reserved, or neither built-in nor defined in your app policy (the message lists the available types). Also when the message has no attachment of a type the mark requires: `audio`, `voiceRecording` or `video` for `played` on its defaults. |
| `403`                                                  | The user is not a member of the channel, does not have the `CreateMessageMark` permission, is banned from the channel or the app, or (client-side) the channel is disabled.                                                                                                     |
| `404`                                                  | The user cannot see the message.                                                                                                                                                                                                                                                |

The checks run in this order: the app grant, the message, then membership, permission and bans (`403`), then the channel type, the member limit and the attachment (`400`). A user who is not a member of the channel gets the `403` even when the channel type lists no marks, and the `403` text does not name the channel.

## Thread replies

A reply in a thread is marked like any other message, on its own attachments. A text reply under a voice note cannot be marked, and a mark on a voice-note reply belongs to the reply alone, never to the parent. The `message.mark_added` event for a reply carries `parent_id`, and replies carry `mark_groups` and `own_marks` like top-level messages.

## Reading marks

Marks come back on messages when you query a channel, fetch a message, read the replies of a thread, or get or query threads. Two fields carry them, and both are left out when there is nothing to show:

- `mark_groups`, on messages the current user authored. For each type it has the count of every user who marked the message and the newest 100 of them in `latest_by`, newest first. Hidden marks are not counted. See [Privacy and shadow bans](#privacy-and-shadow-bans).
- `own_marks`, on other users' messages: the marks the current user put on that message, whatever their read-receipt setting.

```json
{
  "id": "voice-note-1",
  "attachments": [{ "type": "voiceRecording", "asset_url": "..." }],
  "mark_groups": {
    "played": {
      "count": 2,
      "latest_by": [
        { "user_id": "bob", "created_at": "2026-11-06T10:05:00.000Z" },
        { "user_id": "alice", "created_at": "2026-11-06T10:00:00.000Z" }
      ]
    }
  }
}
```

On a message authored by someone else, the same user sees:

```json
{
  "id": "voice-note-2",
  "own_marks": [{ "type": "played", "created_at": "2026-11-06T10:07:00.000Z" }]
}
```

Marks are optional extras on a read. If the marks cannot be read, the messages still come back, without `mark_groups` and `own_marks`.

In threads, both fields are on each reply that the get replies endpoint returns, and on the `parent_message` and the `latest_replies` of a thread returned by get thread and query threads. Search results and quoted copies of a message do not carry them. If a message shows no marks, that can mean there are none, or that marks are off for the channel type or the message does not qualify. Read `mark_types` and the `send-message-mark` capability to tell them apart.

Marks survive a soft delete and an undelete of the message. They are removed with the message by a hard delete, a channel delete, a truncation or a retention policy, and with the user by a user delete.

## Listing marks

`mark_groups` carries the count of every marker but only the newest 100. To see every user who marked a message, with their user objects, list the marks one page at a time with `POST /messages/{id}/marks/query`. The list is newest first, and the order cannot be changed. Like every POST, it returns `201`.

Only the message author can list client-side. From the server side, pass the author's `user_id` to list as the author. Without `user_id` the call lists as the server, with no author check.

```bash
curl -X POST "https://chat.stream-io-api.com/messages/voice-note-1/marks/query?api_key=${API_KEY}" \
  -H "Authorization: ${SERVER_TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "type": "played" }, "limit": 50 }'
```

Every field of the request is optional:

- `filter.type`: one mark type. Without it, every type the channel type lists is returned.
- `limit`: page size, 1 to 100, default 25.
- `next`: the `next` value of the previous page.

The response carries the page and, when more marks exist, the cursor of the next page:

```json
{
  "marks": [
    {
      "type": "played",
      "message_id": "voice-note-1",
      "user_id": "bob",
      "user": { "id": "bob", "name": "Bob" },
      "created_at": "2026-11-06T10:05:00.000Z"
    },
    {
      "type": "played",
      "message_id": "voice-note-1",
      "user_id": "alice",
      "user": { "id": "alice", "name": "Alice" },
      "created_at": "2026-11-06T10:00:00.000Z"
    }
  ],
  "next": "eyJjIjoiMjAyNi0xMS0wNlQxMDowMDowMFoiLCJ1IjoiYWxpY2UifQ",
  "duration": "1.20ms"
}
```

Send `next` back unchanged to get the following page. The last page has no `next`. Treat the cursor as opaque: it marks the position of the last mark on the page, so a page is never repeated or skipped while new marks arrive, including marks that share the same time. Marks are ordered by `created_at` newest first, then by `user_id` and `type`. A cursor the API did not return is a `400`.

The errors:

- `400`, error code `19`: marks are not enabled for the app, or the channel type does not list the `filter.type` (or lists no mark types at all).
- `400`: `filter.type` is not a built-in type or one your app policy defines, or `limit` is out of range.
- `403`: the user is not a member of the channel, does not have permission to read it, or is not the message author.
- `404`: the user cannot see the message.

A message the user deleted for themselves lists as empty. A thread reply lists its own marks.

## Events

A written mark sends one `message.mark_added` event over the websocket to the message author and to the user who marked it, on every device each of them has connected. Other members and watchers of the channel do not receive it. The event is not sent to webhooks or as a push notification. The author does not receive it when they have deleted the message for themselves. Events are limited to 10 per second per recipient and the excess is dropped, and an event can be lost after the mark is stored. The mark itself is never lost, so fetching the message again shows it.

```json
{
  "type": "message.mark_added",
  "cid": "messaging:general",
  "channel_type": "messaging",
  "channel_id": "general",
  "message_id": "voice-note-1",
  "user": { "id": "bob" },
  "mark": {
    "type": "played",
    "message_id": "voice-note-1",
    "user_id": "bob",
    "created_at": "2026-11-06T10:05:00.000Z"
  },
  "created_at": "2026-11-06T10:05:00.000Z"
}
```

When the marked message is a reply in a thread, the event also carries `parent_id`, the ID of the thread's parent message, as the typing and reminder events do. Use it to route the event to the thread view. The event for a top-level message has no `parent_id`.

Apply the event as a set: add the mark keyed by message, user and type if it is not there yet, and never increment a counter blindly, since every device of both users receives the same event. When another event replaces a message in your local state (`message.updated`, `reaction.new`), keep the `mark_groups` and `own_marks` you already hold, the way the JavaScript SDK keeps `own_reactions`.

The event is not replayed by `/sync`. A mark written while a device was offline arrives when the device fetches the channel again, not on reconnect.

## Privacy and shadow bans

A mark can be stored hidden. A hidden mark is accepted and returns `created: true`, the marker gets the event, and it shows in the marker's own `own_marks`. The message author never learns of it: no event, no entry in `mark_groups` (the count does not include it), and no row in the marks listing. A mark is stored hidden in three cases:

- The marker is shadow-banned, in the channel or app-wide.
- The message is from a shadow-banned author.
- The app policy has `privacy.respect_read_receipts` set to `true` and the marker has their [read receipts](https://getstream.io/chat/docs/ruby/message-delivery-and-read-status/#read-receipts) turned off.

This is decided when the mark is written. Changing the policy switch, the user's read-receipt setting or a ban later does not change earlier marks.

## Play threshold

The server records a `played` mark when a client sends it. When a client sends it is up to the SDK: by default it marks the first play, and the SDK can be configured to wait for a longer listen. There is no threshold setting on the server.

## Limits

| Limit                                         | Value                                                                                                                                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Members in a channel for marks to work        | 100 by default. A type can lower it with `max_members` (1 to 100). A mark is accepted when the channel's member count is known and at most that many at the time it is written. Marks already written keep showing if the channel grows past it. |
| Mark types in an app policy                   | 20                                                                                                                                                                                                                                               |
| `requires` entries per type                   | 10                                                                                                                                                                                                                                               |
| Custom type name                              | 32 characters, namespaced and lowercase                                                                                                                                                                                                          |
| `latest_by` entries per type in `mark_groups` | 100, newest first. `count` is always the full count.                                                                                                                                                                                             |
| Page size when listing marks                  | 1 to 100, default 25                                                                                                                                                                                                                             |
| `message.mark_added` events                   | 10 per second per recipient                                                                                                                                                                                                                      |

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/ruby/message-marks/](https://getstream.io/chat/docs/ruby/message-marks/).