API Reference

List Conversations

Overview

Retrieve a paginated list of conversations for the authenticated tenant workspace.

Use this endpoint to power inbox views, conversation browsers, and admin dashboards. Results can be filtered by type, free-text search, and custom metadata keys your app stores on conversations.

When to use this endpoint?

Use List Conversations when:

Building an inbox or conversation list UI for the tenant.
Paginating through conversations with page and limit.
Filtering by conversation type, search text, or metadata fields.
Refreshing list views after create, update, or delete operations.

For a single conversation's full detail, use Conversations → Get Conversation Detail.

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

Authentication

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.
type	group	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)

Returns a paginated list of conversations plus pagination metadata.

json

{
  "success": true,
  "message": "Conversations fetched successfully",
  "data": {
    "list": [
      {
          "_id": "6a57...611e",
          "conversationType": "group",
          "participants": [
              {
                  "_id": "6a3c...14fe",
                  "name": "chat3"
              },
              {
                  "_id": "6a57...11dd",
                  "name": "liam"
              }
          ],
          "owner": "6a57...11dd",
          "groupName": "Group Name",
          "groupImage": "https://example.com/group-image.png",
          "createdAt": "2026-07-15T09:19:59.711Z",
          "updatedAt": "2026-07-17T05:47:45.969Z",
          "lastMessage": {
              "_id": "6a57...6131",
              "content": "Only admins can change this group's settings. The ability to edit sent messages has been disabled",
              "type": "text",
              "createdAt": "2026-07-15T09:24:44.362Z"
          },
          "metadata": {
            "workspaceId": "c1"
          },
          "participantCount": 2
      },      
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 1,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Common Errors

Listing fails when authentication or tenant headers are missing or invalid.

Code	Reason
400 Bad Request	Query parameters are missing or invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Client account is inactive or tenant access is restricted.
500 Internal Server Error	An unexpected error occurred while fetching conversations.

Best Practices

Always send Authorization, is-tenant: true, and x-client-id for tenant-scoped conversation APIs.
Keep limit reasonable for UI performance; use pagination instead of loading everything at once.
Discover available metadata keys with Conversations → Get Conversation Metadata Keys before building filter UIs.
Refresh the list after update, delete, or bulk-delete so the inbox stays in sync.
Use HTTPS for all authenticated requests.

Ready to browse conversations

You can now load tenant conversations and open a specific thread with Conversations → Get Conversation Detail or Conversations → Get Conversation Messages.

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

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.

type

group

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": "Conversations fetched successfully", "data": { "list": [ { "_id": "6a57...611e", "conversationType": "group", "participants": [ { "_id": "6a3c...14fe", "name": "chat3" }, { "_id": "6a57...11dd", "name": "liam" } ], "owner": "6a57...11dd", "groupName": "Group Name", "groupImage": "https://example.com/group-image.png", "createdAt": "2026-07-15T09:19:59.711Z", "updatedAt": "2026-07-17T05:47:45.969Z", "lastMessage": { "_id": "6a57...6131", "content": "Only admins can change this group's settings. The ability to edit sent messages has been disabled", "type": "text", "createdAt": "2026-07-15T09:24:44.362Z" }, "metadata": { "workspaceId": "c1" }, "participantCount": 2 }, ], "pagination": { "currentPage": 1, "totalCount": 1, "hasNextPage": false, "hasPreviousPage": false, "pageSize": 10 } }, "error": null }

Code

Reason

400 Bad Request

Query parameters are missing or invalid.

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Client account is inactive or tenant access is restricted.

500 Internal Server Error

An unexpected error occurred while fetching conversations.