API Reference
Get Conversation Messages
Overview
Retrieve a paginated message history for one conversation, identified by conversationId in the path.
This nested endpoint returns only messages that belong to that conversation — not a tenant-wide message list. Use it to render the chat thread, scroll older pages, and show sender details for each message.
When to use this endpoint?
Use Get Conversation Messages when:
- Opening a chat view for a specific
conversationId. - Paginating older or newer messages within that conversation only.
- Loading sender names and content for a thread after Get Conversation Detail.
- Refreshing the message list after send, edit, or delete actions in that conversation.
For tenant-wide message searches across conversations, use the Messages list endpoints instead — this route is scoped to a single conversation.
{baseUrl}/api/{apiVersion}/client/conversations/:conversationId/messages?page=1&limit=10Authentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Access Token from Login Client or Register Client. |
| 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. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| conversationId | string | The conversation’s _id (24-char Mongo ObjectId). Messages are returned only for this conversation. |
Success Response (HTTP 200 OK)
Returns a paginated list of messages for the given conversationId, including sender info and pagination metadata.
{
"success": true,
"message": "Messages fetched successfully",
"data": {
"list": [
{
"_id": "6a57...114a",
"conversationId": "6a57...112c",
"sender": {
"_id": "6a3c...14fe",
"name": "chat3"
},
"isSystemMessage": false,
"content": "hii",
"type": "text",
"isEdited": false,
"isForwarded": false,
"status": "sent",
"readBy": [],
"starredBy": [],
"deletedFor": [],
"isDeletedForEveryone": false,
"attachments": [],
"reactions": [
{
"reaction": "😃",
"addedBy": "6a57...1113",
"addedAt": "2026-07-15T08:33:40.671Z",
"_id": "6a57...1150"
},
],
"metadata": {
"workspaceId": "c1"
},
"createdAt": "2026-07-15T08:20:39.963Z",
"updatedAt": "2026-07-15T08:33:45.989Z",
"__v": 4
},
],
"pagination": {
"currentPage": 1,
"totalCount": 1,
"hasNextPage": true,
"hasPreviousPage": false,
"pageSize": 10
}
},
"error": null
}Common Errors
Message fetch fails when conversationId is invalid or the request is not authenticated for the tenant.
| Code | Reason |
|---|---|
| 400 Bad Request | Path or query parameters are missing or invalid. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | No conversation exists for the given conversationId. |
| 500 Internal Server Error | An unexpected error occurred while fetching messages. |
Best Practices
- Always pass the correct
conversationId— results are scoped to that conversation only. - Use pagination (
page/limit) for long threads instead of large single loads. - Load conversation metadata first with Get Conversation Detail, then fetch messages for the thread.
- Include tenant headers and a valid Bearer token on every request.
Thread messages ready
You are loading messages for a single conversationId. Combine this with Conversations → Get Conversation Detail to build a full chat screen.