API Reference
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. |
{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.
{
"success": true,
"message": "Starred messages fetched successfully",
"data": {
"list": [
{
"_id": "6964bee12167004f0effe591",
"content": "How are you????",
"type": "text",
"createdAt": "2026-01-12T09:29:05.934Z",
"updatedAt": "2026-01-27T12:23:49.666Z",
"status": "read"
},
{
"_id": "6a4e...ef5c",
"content": "",
"type": "image",
"attachments": [
{
"url": "https://example.com/image.jpg",
"filename": "image.jpg",
"fileType": "image/jpeg",
"size": 18483,
"width": 297,
"height": 170,
"uploadedAt": "2026-07-08T11:35:24.704Z",
"caption": "caption1",
"starredBy": [],
"deletedFor": [],
"isDeletedForEveryone": false,
"_id": "6a4e...ef5d",
"reactions": []
}
],
"status": "sent",
"createdAt": "2026-07-08T11:35:36.324Z",
"updatedAt": "2026-07-19T13:18:48.607Z"
}
]
},
"error": null
}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
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 403 Forbidden — Access denied
{
"success": false,
"message": "Access denied: insufficient permissions",
"data": null,
"error": null
}HTTP 404 Not Found — Conversation not found
{
"success": false,
"message": "Conversation not found",
"data": null,
"error": null
}| 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
isLoggedUserStarredfrom List Messages in sync when the user stars/unstars from the thread without waiting for a full refetch. - Sort by
createdAtdescending so recently sent starred messages appear first. - On row tap, navigate to the thread and scroll to
_idusing 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.