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 and from the per-channel read and delivered receipts.
Marks are off by default. Stream enables them per app, it is not a setting you can turn on yourself. Contact support to enable them for your app.
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:
- Stream has enabled marks for your app.
- The channel type lists the mark type in
mark_types. - 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 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.
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.
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 asplayedoverrides 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 namesread,unread,delivered,sent,seenandfailedare reserved. types.<name>.requires: the attachmenttypevalues 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 withoutvideoturns video off forplayed, 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: whentrue, a mark by a user whose read receipts are off is kept for that user only. See Privacy and shadow bans. Defaults tofalse.
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: falseand does nothing else. Themarkin that response is the stored mark, with its originalcreated_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 returnscreated: falsewith the stored time, the user gets the event and finds the mark inown_marks, and the author never does. See Privacy and shadow bans. - A message the user deleted for themselves answers like a first write:
created: trueand a mark stamped with the current time. Nothing is stored and no event is sent, so a repeat call on such a message answerscreated: trueagain.
Like every POST, a successful call returns 201.
// The current user played the voice note.
const { mark, created } = await channel.sendMessageMark(
{ id: messageId },
{ type: "played" },
);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:
{
"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 inlatest_by, newest first. Hidden marks are not counted. See Privacy and shadow bans.own_marks, on other users' messages: the marks the current user put on that message, whatever their read-receipt setting.
{
"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:
{
"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.
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: thenextvalue of the previous page.
The response carries the page and, when more marks exist, the cursor of the next page:
{
"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 code19: marks are not enabled for the app, or the channel type does not list thefilter.type(or lists no mark types at all).400:filter.typeis not a built-in type or one your app policy defines, orlimitis 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.
{
"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_receiptsset totrueand the marker has their 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 |