API Reference

List Messages

Overview

Retrieve a paginated list of messages in the current tenant workspace.

Filter by conversation, sender, message type, text search, or custom metadata. The response includes message summaries with sender details and pagination metadata for inbox views, moderation tools, and history browsers.

When to use this endpoint?

Use List Messages when:

You need to display messages in an admin inbox, moderation queue, or history table.
You want to scope results to a conversation, sender, or message type.
You are searching message content or filtering with metadata.<key> values.
You need pagination details such as total count and next/previous page flags.

GET{baseUrl}/api/{apiVersion}/client/messages?page=1&limit=10

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
is-tenant	true	Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Query Parameters

Parameter	Example	Description
page	1	Page number, 1-based. Default 1.
limit	10	Page size — items per page. Default 10.
conversationId	—	Conversation _id to scope results to (24-char Mongo ObjectId).
sender	—	Filter by sender userId (24-char Mongo ObjectId).
type	text	Filter by type (message type: text / image / file).
search	—	Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint’s searchable fields.
metadata.workspaceId	c1	Filter on custom metadata. Matches metadata.workspaceId exactly — use any metadata.<yourKey>=value your app stores.

Success Response (HTTP 200 OK)

On success, the API returns a paginated list of messages for the tenant.

json

{
  "success": true,
  "message": "Messages fetched successfully",
  "data": {
    "list": [
      {
        "_id": "6a59...aa9e",
        "conversationId": "6a3c...155e",
        "sender": {
            "_id": "6a35...daa8",
            "name": "chat1"
        },
        "isSystemMessage": false,
        "content": "Gelato is the best ice cream in the world",
        "type": "text",
        "isEdited": false,
        "isForwarded": false,
        "status": "read",
        "readBy": [
            "6a3c...14fe"
        ],
        "starredBy": [],
        "deletedFor": [],
        "isDeletedForEveryone": false,
        "attachments": [],
        "reactions": [],
        "createdAt": "2026-07-17T08:06:36.626Z",
        "updatedAt": "2026-07-17T08:06:41.697Z",
        "__v": 0
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 1,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

HTTP 200 OK means the list was fetched successfully. Requests fail when tenant headers or authentication are missing or invalid.

Code	Reason
400 Bad Request	Required headers are missing or query parameters are invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching messages.

Best Practices

Always send is-tenant: true and a valid x-client-id for tenant-scoped message lists.
Keep limit reasonable for UI tables; use pagination.hasNextPage to load more pages.
Prefer conversationId, search, and typed filters over fetching all messages client-side.
Discover available metadata keys with Get Message Metadata Keys before building metadata.<key> filters.
Refresh the list after update, delete, or bulk-delete operations so the UI stays in sync.

Ready to browse messages

With a valid Access Token and tenant headers, you can list messages and update or remove a single record using the returned _id. Continue with Update Message or Delete Message.

Header

Value

Description

is-tenant

true

Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

x-client-id

Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Parameter

Example

Description

page

Page number, 1-based. Default 1.

limit

Page size — items per page. Default 10.

conversationId

—

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

sender

—

Filter by sender userId (24-char Mongo ObjectId).

type

text

Filter by type (message type: text / image / file).

—

Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint’s searchable fields.

metadata.workspaceId

Filter on custom metadata. Matches metadata.workspaceId exactly — use any metadata.<yourKey>=value your app stores.

{ "success": true, "message": "Messages fetched successfully", "data": { "list": [ { "_id": "6a59...aa9e", "conversationId": "6a3c...155e", "sender": { "_id": "6a35...daa8", "name": "chat1" }, "isSystemMessage": false, "content": "Gelato is the best ice cream in the world", "type": "text", "isEdited": false, "isForwarded": false, "status": "read", "readBy": [ "6a3c...14fe" ], "starredBy": [], "deletedFor": [], "isDeletedForEveryone": false, "attachments": [], "reactions": [], "createdAt": "2026-07-17T08:06:36.626Z", "updatedAt": "2026-07-17T08:06:41.697Z", "__v": 0 } ], "pagination": { "currentPage": 1, "totalCount": 1, "hasNextPage": true, "hasPreviousPage": false, "pageSize": 10 } }, "error": null }

Code

Reason

400 Bad Request

Required headers are missing or query parameters are invalid.

401 Unauthorized

Access Token is missing, invalid, or expired.

500 Internal Server Error

An unexpected error occurred while fetching messages.