API Reference
Get Conversation Detail
Overview
Fetch the full detail of a single conversation by its conversationId.
The response includes participants, group admins, owner, and message count — everything you need for a conversation header, settings panel, or admin detail view.
When to use this endpoint?
Use Get Conversation Detail when:
- Opening a conversation from a list or deep link.
- Displaying participants, admins, and owner information in the UI.
- Loading conversation metadata before update or delete actions.
- Confirming a conversation exists before fetching its messages.
To load the message thread for this conversation, use Conversations → Get Conversation Messages.
{baseUrl}/api/{apiVersion}/client/conversations/:conversationIdAuthentication
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. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| conversationId | string | The conversation’s _id (24-char Mongo ObjectId). |
Success Response (HTTP 200 OK)
Returns the conversation document with populated participants, admins, and owner.
{
"success": true,
"message": "Conversation fetched successfully",
"data": {
"_id": "6a57...611e",
"conversationType": "group",
"participants": [
{
"_id": "6a3c...14fe",
"name": "chat3",
"email": "chat3@yopmail.com",
"isActive": true
},
{
"_id": "6a57...11dd",
"name": "liam",
"email": "liam@yopmail.com",
"isActive": true
}
],
"owner": {
"_id": "6a57...11dd",
"name": "liam",
"email": "liam@yopmail.com"
},
"groupName": "Group Name",
"groupImage": "https://example.com/group-image.png",
"groupDescription": "add here",
"groupAdmins": [
{
"_id": "6a57...11dd",
"name": "liam",
"email": "liam@yopmail.com"
}
],
"groupPermissions": {
"onlyAdminCanSendMessage": false,
"onlyAdminCanEditInfo": true,
"senderCanEditMessage": false,
"allowMemberAdd": false,
"allowMemberRemove": false,
"moderationEnabled": false
},
"unreadCount": {},
"pinnedMessage": [],
"createdAt": "2026-07-15T09:19:59.711Z",
"updatedAt": "2026-07-17T05:47:45.969Z",
"__v": 0,
"lastMessage": "6a57...6131",
"messageCount": 2,
"metadata": {
"workspaceId": "c1"
}
}
"error": null
}Common Errors
Detail fetch fails when the conversation ID is invalid or the request is not authenticated for the tenant.
| Code | Reason |
|---|---|
| 400 Bad Request | conversationId is missing or not a valid ObjectId. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | No conversation exists for the given conversationId in this tenant. |
| 500 Internal Server Error | An unexpected error occurred while fetching the conversation. |
Best Practices
- Pass a valid 24-character Mongo ObjectId as
conversationId. - Cache detail responses briefly in the UI, then re-fetch after updates.
- Use Get Conversation Messages for the message thread — this endpoint returns conversation metadata, not the full message list.
- Always include tenant headers (is-tenant and x-client-id) with a valid Bearer token.
Conversation detail loaded
Next, open the message history with Conversations → Get Conversation Messages, or edit group settings via Conversations → Update Conversation.