List Conversations

Overview

Retrieve a paginated list of conversations the signed-in chat user participates in - for the inbox sidebar, conversation search, and filtered views inside the messaging UI.

Each row includes conversation type, participant summaries, group details when relevant, unread / pin / star counts, timestamps, and a preview of the last message so you can render the inbox sidebar and jump into a thread.

When to use this endpoint?

Use List Conversations when:

Bootstrapping the chat inbox on app load or after login.
Paginating the conversation list as the user scrolls the sidebar.
Searching conversations by name or other searchable fields via search.
Filtering to DMs vs groups with conversationType, or scoping by custom metadata.category.

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

Response Data

Each item in data.list typically includes:

Field	Description
_id	Conversation id - pass to Get Conversation Info, message APIs, and attachment endpoints.
conversationType	`individual` (DM) or `group`.
participants	Array of participant objects with `_id` and `name` - enough to render avatars and titles in the inbox without an extra user fetch.
owner	Group owner user id. Present for group conversations; may be omitted for individual chats.
groupName	Display name for group chats. Use in the inbox title when `conversationType` is `group`.
groupDescription	Optional group description text for group conversations.
unreadCount	Number of unread messages for the signed-in user in this conversation - use for inbox badges.
lastMessage	Preview of the most recent message: `_id`, `content`, `type`, `status`, and `createdAt`.
pinnedCount	Count of pinned messages in this conversation.
starredCount	Count of starred messages in this conversation.
createdAt / updatedAt	ISO timestamps for when the conversation was created and last updated. Prefer `updatedAt` for inbox sort order.

data.pagination includes currentPage, totalCount, hasNextPage, hasPreviousPage, and pageSize.

GET{baseUrl}/api/{apiVersion}/conversation/list?limit=10&page=1&search=chat1

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
limit	Optional	10	Page size - items per page. Default 10.
page	Optional	1	Page number, 1-based. Default 1.
search	Optional	chat1	Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint's searchable fields.
conversationType	Optional	group	Filter by conversation type: "individual" or "group".
owner	Optional	—	Filter by the group owner's userId (24-char Mongo ObjectId).
metadata.category	Optional	support	Filter on custom metadata. Matches `metadata.category` exactly - use any `metadata.<yourKey>=value` your app stores.

Success Response (HTTP 200 OK)

On success, the API returns list and pagination. Use lastMessage for inbox previews, unreadCount for badges, and updatedAt for sort order.

json

1{2  "success": true,3  "message": "Conversation list fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a4b...3f8b",8        "conversationType": "group",9        "participants": [10            {11                "_id": "6a47...adb",12                "name": "Iraa"13            },14            {15                "_id": "6a4a...3985",16                "name": "Riva R"17            }18        ],19        "owner": "6a4a...8cb7",20        "groupName": "Group Name",21        "groupDescription": "Group Description",22        "unreadCount": 0,23        "createdAt": "2026-07-06T04:57:46.196Z",24        "updatedAt": "2026-07-10T09:39:25.210Z",25        "lastMessage": {26            "_id": "6a4b...3faf",27            "content": "Hello",28            "type": "text",29            "status": "sent",30            "createdAt": "2026-07-06T04:57:55.851Z"31        },32        "pinnedCount": 0,33        "starredCount": 034      }35    ],36    "pagination": {37      "currentPage": 1,38      "totalCount": 1,39      "hasNextPage": false,40      "hasPreviousPage": false,41      "pageSize": 1042    }43  },44  "error": null45}

Common Errors

List fails when the token is missing, invalid, or the user lacks access to conversations 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}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Insufficient permissions to list conversations in this tenant.
500 Internal Server Error	An unexpected error occurred while listing conversations.

Best Practices

Load page 1 on inbox mount; fetch the next page when the user scrolls near the bottom of the sidebar.
Debounce search input (300–500 ms) before calling the API to avoid excessive requests.
Merge list results with real-time socket events so new messages update previews without a full refetch.
Use conversationType tabs or filters in the UI rather than client-side filtering of large lists.
Always send tenant headers with the chat user Bearer token over HTTPS.

Inbox ready

Bind the list to your conversation sidebar. Tap a row to open the thread with Get Conversation Info, then load messages for the active chat.

Overview

Retrieve a paginated list of conversations the signed-in chat user participates in - for the inbox sidebar, conversation search, and filtered views inside the messaging UI.

When to use this endpoint?

Use List Conversations when:

Bootstrapping the chat inbox on app load or after login.
Paginating the conversation list as the user scrolls the sidebar.
Searching conversations by name or other searchable fields via search.
Filtering to DMs vs groups with conversationType, or scoping by custom metadata.category.

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

Response Data

Each item in data.list typically includes:

Field	Description
_id	Conversation id - pass to Get Conversation Info, message APIs, and attachment endpoints.
conversationType	`individual` (DM) or `group`.
participants	Array of participant objects with `_id` and `name` - enough to render avatars and titles in the inbox without an extra user fetch.
owner	Group owner user id. Present for group conversations; may be omitted for individual chats.
groupName	Display name for group chats. Use in the inbox title when `conversationType` is `group`.
groupDescription	Optional group description text for group conversations.
unreadCount	Number of unread messages for the signed-in user in this conversation - use for inbox badges.
lastMessage	Preview of the most recent message: `_id`, `content`, `type`, `status`, and `createdAt`.
pinnedCount	Count of pinned messages in this conversation.
starredCount	Count of starred messages in this conversation.
createdAt / updatedAt	ISO timestamps for when the conversation was created and last updated. Prefer `updatedAt` for inbox sort order.

data.pagination includes currentPage, totalCount, hasNextPage, hasPreviousPage, and pageSize.

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.

Query Parameters

Parameter	Required	Example	Description
limit	Optional	10	Page size - items per page. Default 10.
page	Optional	1	Page number, 1-based. Default 1.
search	Optional	chat1	Case-insensitive text search (input is regex-escaped, safe). Matches this endpoint's searchable fields.
conversationType	Optional	group	Filter by conversation type: "individual" or "group".
owner	Optional	—	Filter by the group owner's userId (24-char Mongo ObjectId).
metadata.category	Optional	support	Filter on custom metadata. Matches `metadata.category` exactly - use any `metadata.<yourKey>=value` your app stores.

Success Response (HTTP 200 OK)

On success, the API returns list and pagination. Use lastMessage for inbox previews, unreadCount for badges, and updatedAt for sort order.

json

1{2  "success": true,3  "message": "Conversation list fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a4b...3f8b",8        "conversationType": "group",9        "participants": [10            {11                "_id": "6a47...adb",12                "name": "Iraa"13            },14            {15                "_id": "6a4a...3985",16                "name": "Riva R"17            }18        ],19        "owner": "6a4a...8cb7",20        "groupName": "Group Name",21        "groupDescription": "Group Description",22        "unreadCount": 0,23        "createdAt": "2026-07-06T04:57:46.196Z",24        "updatedAt": "2026-07-10T09:39:25.210Z",25        "lastMessage": {26            "_id": "6a4b...3faf",27            "content": "Hello",28            "type": "text",29            "status": "sent",30            "createdAt": "2026-07-06T04:57:55.851Z"31        },32        "pinnedCount": 0,33        "starredCount": 034      }35    ],36    "pagination": {37      "currentPage": 1,38      "totalCount": 1,39      "hasNextPage": false,40      "hasPreviousPage": false,41      "pageSize": 1042    }43  },44  "error": null45}

Common Errors

List fails when the token is missing, invalid, or the user lacks access to conversations 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}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Insufficient permissions to list conversations in this tenant.
500 Internal Server Error	An unexpected error occurred while listing conversations.

Best Practices

Load page 1 on inbox mount; fetch the next page when the user scrolls near the bottom of the sidebar.
Debounce search input (300–500 ms) before calling the API to avoid excessive requests.
Merge list results with real-time socket events so new messages update previews without a full refetch.
Use conversationType tabs or filters in the UI rather than client-side filtering of large lists.
Always send tenant headers with the chat user Bearer token over HTTPS.