API Reference

List Messages

Overview

Retrieve a paginated list of messages for a conversation — for the main chat thread, message history, and scroll-back inside the messaging UI.

Each item includes sender info, content, delivery status, read receipts, reactions, pin/star flags for the signed-in user, and soft-delete metadata so you can render bubbles, system events, and action menus without extra round-trips.

When to use this endpoint?

Use List Messages when:

Opening a conversation thread and loading the initial message history.
Paginating older messages as the user scrolls up (infinite scroll / load-more).
Refreshing the thread after reconnect or when returning to an active chat.
Hydrating message state before merging real-time socket updates.

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 for replies, reactions, pin/star actions, and socket event correlation.
conversationId	Parent conversation id — should match the `conversationId` query param.
sender	Sender summary with `_id` and `name` — enough to render avatars and author labels in the thread.
content	Message body text (or caption for media types). May be omitted for attachment-only messages.
type	Message type — e.g. `text`, `image`, `video`, `audio`, `file`.
status	Delivery status for the signed-in user — e.g. `sent`, `delivered`, `read`.
isEdited	Whether the message content was edited after send — show an "edited" label when true.
isForwarded	Whether the message was forwarded from another conversation.
isSystemMessage	System/event message (member joined, group updated, etc.) — render with a distinct style instead of a user bubble.
readBy	Participants who have read the message — array of `_id` and `name`.
starredBy	Users who starred this message.
deletedFor	User ids for whom this message is soft-deleted (delete for me).
isDeletedForEveryone	Whether the message was deleted for all participants — show a placeholder instead of content when true.
reactions	Emoji reactions on the message — use for reaction chips under the bubble.
isLoggedUserStarred	Whether the signed-in user has starred this message — toggle star icon state in the thread.
isPinnedMessage	Whether this message is pinned in the conversation — pair with Pinned Messages for the pinned banner/list.
createdAt / updatedAt	ISO timestamps for send time and last update. Use `createdAt` for bubble ordering and date separators.

data.pagination includes currentPage, totalCount, hasNextPage, hasPreviousPage, and pageSize. Increment page while hasNextPage is true to load older messages.

GET

{baseUrl}/api/{apiVersion}/message/get-all-from-conversation?conversationId={conversationId}&page=1&limit=10&sort=createdAt&sortType=desc

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 results to (24-char Mongo ObjectId).
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	10	Page size — items per page. Default 10.
sort	Optional	createdAt	Field name to sort by. Default "createdAt".
sortType	Optional	desc	Sort direction: "asc" or "desc". Default "desc" (newest first on page 1).

Success Response (HTTP 200 OK)

On success, the API returns list and pagination. Bind list to your message list; use isLoggedUserStarred and isPinnedMessage for per-row UI state.

json

{
  "success": true,
  "message": "Messages fetched successfully",
  "data": {
    "list": [
      {
        "_id": "69b13009db7dd594ba0144f5",
        "conversationId": "69b12d08db7dd594ba013ebc",
        "sender": {
          "_id": "69a91733afd8cb7180a63fb2",
          "name": "chat2"
        },
        "isSystemMessage": false,
        "content": "fgfg",
        "type": "text",
        "isEdited": false,
        "isForwarded": false,
        "status": "read",
        "readBy": [
          {
            "_id": "69a5546ff54a9af3316020c9",
            "name": "chat1"
          },
          {
            "_id": "69aaad3304c46f7cacc7a7a9",
            "name": "chat3"
          }
        ],
        "starredBy": [],
        "deletedFor": [],
        "isDeletedForEveryone": false,
        "reactions": [],
        "createdAt": "2026-03-11T09:04:09.578Z",
        "updatedAt": "2026-03-12T06:25:30.975Z",
        "__v": 0,
        "isLoggedUserStarred": false,
        "isPinnedMessage": false
      },
      {
        "_id": "69b13150db7dd594ba01462e",
        "conversationId": "69b12d08db7dd594ba013ebc",
        "sender": {
          "_id": "69a91733afd8cb7180a63fb2",
          "name": "chat2"
        },
        "isSystemMessage": false,
        "content": "fgfg",
        "type": "text",
        "isEdited": false,
        "isForwarded": false,
        "status": "read",
        "readBy": [
          {
            "_id": "69a5546ff54a9af3316020c9",
            "name": "chat1"
          },
          {
            "_id": "69aaad3304c46f7cacc7a7a9",
            "name": "chat3"
          }
        ],
        "starredBy": [],
        "deletedFor": [],
        "isDeletedForEveryone": false,
        "reactions": [],
        "createdAt": "2026-03-11T09:09:36.032Z",
        "updatedAt": "2026-03-12T06:25:30.975Z",
        "__v": 0,
        "isLoggedUserStarred": false,
        "isPinnedMessage": false
      },
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 13,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

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

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 403 Forbidden — Access denied

json

{
  "success": false,
  "message": "Access denied: insufficient permissions",
  "data": null,
  "error": null
}

HTTP 404 Not Found — Conversation not found

json

{
  "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 messages.

Best Practices

Load page 1 with sortType=desc on thread open; fetch the next page when the user scrolls to the top for infinite scroll of older messages.
Merge list results with real-time socket events (new message, edit, delete, reaction) instead of refetching the full thread on every event.
Respect isDeletedForEveryone and deletedFor before rendering content — hide or show placeholders per user.
Use isSystemMessage to render join/leave and group events inline without treating them as user sends.
Always send tenant headers with the chat user Bearer token over HTTPS.

Thread ready

Bind the list to your chat thread. Use Pinned Messages, Starred Messages, or message search endpoints next for pinned banners, starred screens, and in-thread search.

Field

Description

_id

Message id — use for replies, reactions, pin/star actions, and socket event correlation.

conversationId

Parent conversation id — should match the conversationId query param.

sender

Sender summary with _id and name — enough to render avatars and author labels in the thread.

content

Message body text (or caption for media types). May be omitted for attachment-only messages.

type

Message type — e.g. text, image, video, audio, file.

status

Delivery status for the signed-in user — e.g. sent, delivered, read.

isEdited

Whether the message content was edited after send — show an "edited" label when true.

isForwarded

Whether the message was forwarded from another conversation.

isSystemMessage

System/event message (member joined, group updated, etc.) — render with a distinct style instead of a user bubble.

readBy

Participants who have read the message — array of _id and name.

starredBy

Users who starred this message.

deletedFor

User ids for whom this message is soft-deleted (delete for me).

isDeletedForEveryone

Whether the message was deleted for all participants — show a placeholder instead of content when true.

reactions

Emoji reactions on the message — use for reaction chips under the bubble.

isLoggedUserStarred

Whether the signed-in user has starred this message — toggle star icon state in the thread.

isPinnedMessage

Whether this message is pinned in the conversation — pair with Pinned Messages for the pinned banner/list.

createdAt / updatedAt

ISO timestamps for send time and last update. Use createdAt for bubble ordering and date separators.

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 results to (24-char Mongo ObjectId).

page

Optional

Page number, 1-based. Default 1.

limit

Optional

Page size — items per page. Default 10.

sort

Optional

createdAt

Field name to sort by. Default "createdAt".

sortType

Optional

desc

Sort direction: "asc" or "desc". Default "desc" (newest first on page 1).

{ "success": true, "message": "Messages fetched successfully", "data": { "list": [ { "_id": "69b13009db7dd594ba0144f5", "conversationId": "69b12d08db7dd594ba013ebc", "sender": { "_id": "69a91733afd8cb7180a63fb2", "name": "chat2" }, "isSystemMessage": false, "content": "fgfg", "type": "text", "isEdited": false, "isForwarded": false, "status": "read", "readBy": [ { "_id": "69a5546ff54a9af3316020c9", "name": "chat1" }, { "_id": "69aaad3304c46f7cacc7a7a9", "name": "chat3" } ], "starredBy": [], "deletedFor": [], "isDeletedForEveryone": false, "reactions": [], "createdAt": "2026-03-11T09:04:09.578Z", "updatedAt": "2026-03-12T06:25:30.975Z", "__v": 0, "isLoggedUserStarred": false, "isPinnedMessage": false }, { "_id": "69b13150db7dd594ba01462e", "conversationId": "69b12d08db7dd594ba013ebc", "sender": { "_id": "69a91733afd8cb7180a63fb2", "name": "chat2" }, "isSystemMessage": false, "content": "fgfg", "type": "text", "isEdited": false, "isForwarded": false, "status": "read", "readBy": [ { "_id": "69a5546ff54a9af3316020c9", "name": "chat1" }, { "_id": "69aaad3304c46f7cacc7a7a9", "name": "chat3" } ], "starredBy": [], "deletedFor": [], "isDeletedForEveryone": false, "reactions": [], "createdAt": "2026-03-11T09:09:36.032Z", "updatedAt": "2026-03-12T06:25:30.975Z", "__v": 0, "isLoggedUserStarred": false, "isPinnedMessage": false }, ], "pagination": { "currentPage": 1, "totalCount": 13, "hasNextPage": true, "hasPreviousPage": false, "pageSize": 10 } }, "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 messages.