Starred Messages

Overview

Retrieve starred messages for a conversation - for the starred messages screen in the chat SDK where users browse messages they marked for later.

Returns lightweight message summaries (content preview, type, status, timestamps) scoped to one conversation so you can render a searchable starred list without loading the full thread history.

When to use this endpoint?

Use Starred Messages when:

Opening the "Starred messages" view from the thread header or conversation menu.
Showing all messages the signed-in user starred within the active conversation.
Refreshing the starred list after star/unstar actions or socket updates.
Letting the user jump back to a starred message in the main thread.

Part of the Chat Messages APIs for the chat package/SDK (not Platform → Messages). Requires a chat user Access Token for the signed-in messaging participant.

Response Data

Each item in data.list typically includes:

Field	Description
_id	Message id - use to scroll to the message in the thread or open message detail.
content	Message text preview for the starred list row. May be omitted for attachment-only messages - fall back to type label or thumbnail.
type	Message type - e.g. `text`, `image`, `video`, `audio`, `file`.
status	Delivery/read status - e.g. `sent`, `delivered`, `read`.
createdAt / updatedAt	ISO timestamps for when the message was sent and last updated. Use `createdAt` for list sort and date grouping.

GET{baseUrl}/api/{apiVersion}/message/starred-messages?conversationId={conversationId}

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Chat user Access Token (Bearer) for the signed-in messaging participant.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Query Parameters

Parameter	Required	Example	Description
conversationId	Required	{{conversationId}}	Conversation _id to scope starred results to (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

On success, the API returns a list of starred message summaries for the signed-in user in this conversation. Bind rows to your starred screen; use _id to navigate back to the message in the thread.

json

1{2  "success": true,3  "message": "Starred messages fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6964bee12167004f0effe591",8        "content": "How are you????",9        "type": "text",10        "createdAt": "2026-01-12T09:29:05.934Z",11        "updatedAt": "2026-01-27T12:23:49.666Z",12        "status": "read"13      },14      {15        "_id": "6a4e...ef5c",16        "content": "",17        "type": "image",18        "attachments": [19          {20              "url": "https://example.com/image.jpg",21              "filename": "image.jpg",22              "fileType": "image/jpeg",23              "size": 18483,24              "width": 297,25              "height": 170,26              "uploadedAt": "2026-07-08T11:35:24.704Z",27              "caption": "caption1",28              "starredBy": [],29              "deletedFor": [],30              "isDeletedForEveryone": false,31              "_id": "6a4e...ef5d",32              "reactions": []33          }34        ],35        "status": "sent",36        "createdAt": "2026-07-08T11:35:36.324Z",37        "updatedAt": "2026-07-19T13:18:48.607Z"38      }39    ]40  },41  "error": null42}

Common Errors

Starred list fails when the token is missing, the user is not a participant, or the conversation does not exist in this tenant.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Conversation not found

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	User is not a participant or lacks access to this conversation.
404 Not Found	`conversationId` does not exist or is not visible in this tenant.
500 Internal Server Error	An unexpected error occurred while fetching starred messages.

Best Practices

Load when the user opens the starred screen - no need to prefetch on every thread open unless you show a starred entry point with a count.
Keep isLoggedUserStarred from List Messages in sync when the user stars/unstars from the thread without waiting for a full refetch.
Sort by createdAt descending so recently sent starred messages appear first.
On row tap, navigate to the thread and scroll to _id using your message list state.
Always send tenant headers with the chat user Bearer token over HTTPS.

Starred screen ready

Bind the list to your starred messages view in the chat SDK. Pair with List Messages so selecting a row jumps to the message in the active conversation thread.

Overview

Retrieve starred messages for a conversation - for the starred messages screen in the chat SDK where users browse messages they marked for later.

Returns lightweight message summaries (content preview, type, status, timestamps) scoped to one conversation so you can render a searchable starred list without loading the full thread history.

When to use this endpoint?

Use Starred Messages when:

Opening the "Starred messages" view from the thread header or conversation menu.
Showing all messages the signed-in user starred within the active conversation.
Refreshing the starred list after star/unstar actions or socket updates.
Letting the user jump back to a starred message in the main thread.

Part of the Chat Messages APIs for the chat package/SDK (not Platform → Messages). Requires a chat user Access Token for the signed-in messaging participant.

Response Data

Each item in data.list typically includes:

Field	Description
_id	Message id - use to scroll to the message in the thread or open message detail.
content	Message text preview for the starred list row. May be omitted for attachment-only messages - fall back to type label or thumbnail.
type	Message type - e.g. `text`, `image`, `video`, `audio`, `file`.
status	Delivery/read status - e.g. `sent`, `delivered`, `read`.
createdAt / updatedAt	ISO timestamps for when the message was sent and last updated. Use `createdAt` for list sort and date grouping.

Header

Value

Description

Authorization

Bearer <access_token>

Chat user Access Token (Bearer) for the signed-in messaging participant.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Parameter

Required

Example

Description

conversationId

Required

Conversation _id to scope starred results to (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

json

1{2  "success": true,3  "message": "Starred messages fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6964bee12167004f0effe591",8        "content": "How are you????",9        "type": "text",10        "createdAt": "2026-01-12T09:29:05.934Z",11        "updatedAt": "2026-01-27T12:23:49.666Z",12        "status": "read"13      },14      {15        "_id": "6a4e...ef5c",16        "content": "",17        "type": "image",18        "attachments": [19          {20              "url": "https://example.com/image.jpg",21              "filename": "image.jpg",22              "fileType": "image/jpeg",23              "size": 18483,24              "width": 297,25              "height": 170,26              "uploadedAt": "2026-07-08T11:35:24.704Z",27              "caption": "caption1",28              "starredBy": [],29              "deletedFor": [],30              "isDeletedForEveryone": false,31              "_id": "6a4e...ef5d",32              "reactions": []33          }34        ],35        "status": "sent",36        "createdAt": "2026-07-08T11:35:36.324Z",37        "updatedAt": "2026-07-19T13:18:48.607Z"38      }39    ]40  },41  "error": null42}

Common Errors

Starred list fails when the token is missing, the user is not a participant, or the conversation does not exist in this tenant.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Conversation not found

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	User is not a participant or lacks access to this conversation.
404 Not Found	`conversationId` does not exist or is not visible in this tenant.
500 Internal Server Error	An unexpected error occurred while fetching starred messages.

Best Practices

Load when the user opens the starred screen - no need to prefetch on every thread open unless you show a starred entry point with a count.
Keep isLoggedUserStarred from List Messages in sync when the user stars/unstars from the thread without waiting for a full refetch.
Sort by createdAt descending so recently sent starred messages appear first.
On row tap, navigate to the thread and scroll to _id using your message list state.
Always send tenant headers with the chat user Bearer token over HTTPS.