API Reference
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 custommetadata.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.
{baseUrl}/api/{apiVersion}/conversation/list?limit=10&page=1&search=chat1Authentication
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.
{
"success": true,
"message": "Conversation list fetched successfully",
"data": {
"list": [
{
"_id": "6a4b...3f8b",
"conversationType": "group",
"participants": [
{
"_id": "6a47...adb",
"name": "Iraa"
},
{
"_id": "6a4a...3985",
"name": "Riva R"
}
],
"owner": "6a4a...8cb7",
"groupName": "Group Name",
"groupDescription": "Group Description",
"unreadCount": 0,
"createdAt": "2026-07-06T04:57:46.196Z",
"updatedAt": "2026-07-10T09:39:25.210Z",
"lastMessage": {
"_id": "6a4b...3faf",
"content": "Hello",
"type": "text",
"status": "sent",
"createdAt": "2026-07-06T04:57:55.851Z"
},
"pinnedCount": 0,
"starredCount": 0
}
],
"pagination": {
"currentPage": 1,
"totalCount": 1,
"hasNextPage": false,
"hasPreviousPage": false,
"pageSize": 10
}
},
"error": null
}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
{
"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
}| 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
searchinput (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
conversationTypetabs 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.