API Reference

Update Conversation

Overview

Update editable fields on a group conversation. This endpoint supports partial updates — you can change a single field or several fields in one request.

Only these values can be updated through this endpoint:

groupName
groupDescription
All flags inside groupPermissions
moderationEnabled (within groupPermissions)

Other conversation properties (participants, owner, conversation type, and similar) are managed by dedicated endpoints and are ignored here.

When to use this endpoint?

Use Update Conversation when:

Renaming a group (groupName).
Changing the group about text (groupDescription).
Toggling moderation (groupPermissions.moderationEnabled).
Updating one or more group permission flags from a settings or admin panel.

At least one editable field must be present in the request body. Sending an empty object or only unsupported fields returns 400 Bad Request with No editable fields provided.

Editable Fields

This table lists every field this endpoint accepts. Each field can be updated on its own (single-field update) or combined with others.

Field	Type	Required	Description
groupName	string	Optional	Display name of the group conversation. Can be sent alone to rename the group.
groupDescription	string	Optional	Short description / about text for the group. Can be sent alone to update the description without changing permissions.
groupPermissions	object	Optional	Object containing permission flags. You may send the full object or only the flags you want to change (for example only `moderationEnabled`).

All fields above are optional individually, but the body must include at least one of them.

Single-Field Updates

Because this endpoint is partial, each editable value can be updated independently. Use these patterns when your UI changes one setting at a time.

Update group name only

json

{
  "groupName": "Support Team"
}

Update group description only

json

{
  "groupDescription": "Escalations and priority tickets"
}

Toggle moderation only

moderationEnabled lives inside groupPermissions. Send only that key when enabling or disabling moderation.

json

{
  "groupPermissions": {
    "moderationEnabled": true
  }
}

Update all group permissions

Send the full groupPermissions object when saving a permissions form with every flag.

json

{
  "groupPermissions": {
    "onlyAdminCanSendMessage": true,
    "onlyAdminCanEditInfo": true,
    "senderCanEditMessage": false,
    "allowMemberAdd": false,
    "allowMemberRemove": false,
    "moderationEnabled": true
  }
}

PATCH{baseUrl}/api/{apiVersion}/client/conversations/:conversationId

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).
x-client-id	{{clientId}}	Tenant (client) id. Uses the {{clientId}} variable.
Content-Type	application/json	Required when sending a JSON request body.

Path Parameters

Parameter	Example	Description
conversationId	string	Conversation _id (24-char Mongo ObjectId) of the group to update.

Request Payload

Example combining multiple editable fields in one request. You do not need to send every field — omit anything you are not changing.

json

{
  "groupName": "Support Team",
  "groupDescription": "Escalations and priority tickets",
  "groupPermissions": {
    "onlyAdminCanSendMessage": false,
    "onlyAdminCanEditInfo": true,
    "senderCanEditMessage": true,
    "allowMemberAdd": false,
    "allowMemberRemove": true,
    "moderationEnabled": true
  }
}

Group Permissions

All group permission flags live under groupPermissions. Each boolean is independently editable. Include moderationEnabled here when turning moderation on or off.

Field	Type	Required	Description
onlyAdminCanSendMessage	boolean	Optional	When `true`, only group admins can send messages.
onlyAdminCanEditInfo	boolean	Optional	When `true`, only admins can change group name, description, and related info.
senderCanEditMessage	boolean	Optional	When `true`, senders can edit their own messages.
allowMemberAdd	boolean	Optional	Controls whether members can add participants. When `false`, only admins can add members.
allowMemberRemove	boolean	Optional	Controls whether members can remove participants. When `false`, only admins can remove members.
moderationEnabled	boolean	Optional	Enables advanced message moderation features for the group. Can be updated alone inside `groupPermissions`.

Success Response (HTTP 200 OK)

On success, the API returns the updated conversation with the new field values merged into the existing document.

json

{
  "success": true,
  "message": "Conversation updated successfully",
  "data": {
    "_id": "6a4c...dada",
    "conversationType": "group",
    "participants": [
      "699f...645d",
      "699f...645e"
    ],
    "owner": "699f...645d",
    "groupName": "Support Team",
    "groupDescription": "Escalations and priority tickets",
    "groupPermissions": {
      "onlyAdminCanSendMessage": false,
      "onlyAdminCanEditInfo": true,
      "senderCanEditMessage": true,
      "allowMemberAdd": false,
      "allowMemberRemove": true,
      "moderationEnabled": true
    },
    "metadata": {
      "workspaceId": "c1"
    },
    "createdAt": "2026-07-01T09:12:44.000Z",
    "updatedAt": "2026-07-09T11:30:00.000Z"
  },
  "error": null
}

Error Responses

HTTP 400 Bad Request — No editable fields

Returned when the body is empty or does not include groupName, groupDescription, or groupPermissions.

json

{
  "success": false,
  "message": "No editable fields provided",
  "data": null,
  "error": "No editable fields provided"
}

Common Errors

Update fails when nothing editable is provided, the conversation is missing, or authentication is invalid.

Code	Reason
400 Bad Request	No editable fields provided, or the payload is invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	Conversation not found for the given `conversationId`.
500 Internal Server Error	An unexpected error occurred while updating the conversation.

Best Practices

Prefer single-field updates when the UI edits one control at a time (name, description, or one permission toggle).
When saving a full permissions form, send the complete groupPermissions object so unset flags are explicit.
Never send an empty body — always include at least groupName, groupDescription, or groupPermissions.
Confirm the conversation exists with Get Conversation Detail before updating.
Always send Content-Type: application/json with tenant headers and a Bearer token.

Conversation updated

Refresh your detail view to show the latest group name, description, and permissions. Continue with Get Conversation Detail or return to List Conversations.

Field

Type

Required

Description

groupName

string

Optional

Display name of the group conversation. Can be sent alone to rename the group.

groupDescription

string

Optional

Short description / about text for the group. Can be sent alone to update the description without changing permissions.

groupPermissions

object

Optional

Object containing permission flags. You may send the full object or only the flags you want to change (for example only moderationEnabled).

{ "groupPermissions": { "onlyAdminCanSendMessage": true, "onlyAdminCanEditInfo": true, "senderCanEditMessage": false, "allowMemberAdd": false, "allowMemberRemove": false, "moderationEnabled": true } }

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

x-client-id

Tenant (client) id. Uses the {{clientId}} variable.

Content-Type

application/json

Required when sending a JSON request body.

Parameter

Example

Description

conversationId

string

Conversation _id (24-char Mongo ObjectId) of the group to update.

{ "groupName": "Support Team", "groupDescription": "Escalations and priority tickets", "groupPermissions": { "onlyAdminCanSendMessage": false, "onlyAdminCanEditInfo": true, "senderCanEditMessage": true, "allowMemberAdd": false, "allowMemberRemove": true, "moderationEnabled": true } }

Field

Type

Required

Description

onlyAdminCanSendMessage

boolean

Optional

When true, only group admins can send messages.

onlyAdminCanEditInfo

boolean

Optional

When true, only admins can change group name, description, and related info.

senderCanEditMessage

boolean

Optional

When true, senders can edit their own messages.

allowMemberAdd

boolean

Optional

Controls whether members can add participants. When false, only admins can add members.

allowMemberRemove

boolean

Optional

Controls whether members can remove participants. When false, only admins can remove members.

moderationEnabled

boolean

Optional

Enables advanced message moderation features for the group. Can be updated alone inside groupPermissions.

{ "success": true, "message": "Conversation updated successfully", "data": { "_id": "6a4c...dada", "conversationType": "group", "participants": [ "699f...645d", "699f...645e" ], "owner": "699f...645d", "groupName": "Support Team", "groupDescription": "Escalations and priority tickets", "groupPermissions": { "onlyAdminCanSendMessage": false, "onlyAdminCanEditInfo": true, "senderCanEditMessage": true, "allowMemberAdd": false, "allowMemberRemove": true, "moderationEnabled": true }, "metadata": { "workspaceId": "c1" }, "createdAt": "2026-07-01T09:12:44.000Z", "updatedAt": "2026-07-09T11:30:00.000Z" }, "error": null }

Code

Reason

400 Bad Request

No editable fields provided, or the payload is invalid.

401 Unauthorized

Access Token is missing, invalid, or expired.

404 Not Found

Conversation not found for the given conversationId.

500 Internal Server Error

An unexpected error occurred while updating the conversation.