API Reference

Update Group Information

Overview

Update a group conversation's display information — name, description, avatar image URL, and optional metadata. Use this from the SDK group profile or settings screen when an admin or permitted member edits group details.

Only the fields you send are updated; omit fields you want to leave unchanged. The response returns the full updated conversation document.

When to use this endpoint?

Use Update Group Information when:

A user renames the group from the SDK header or info panel.
You update the group description or avatar after branding changes.
You sync metadata from an external workspace (project id, channel slug, and so on).
You save changes from a group edit form after loading conversation details.

Part of the Chat Conversation APIs for the chat package / SDK — not Platform → Conversations. Requires a chat user Bearer token; editing may be restricted when onlyAdminCanEditInfo is true.

Request Fields

Field	Type	Required	Description
conversationId	string	Required	The group conversation's `_id`.
groupName	string	Optional	New display name for the group in the SDK conversation list and header.
groupDescription	string	Optional	Updated description shown in group info screens.
groupImage	string	Optional	URL for the group avatar. Upload the image to your CDN or storage first, then pass the public URL here.
metadata	object	Optional	Arbitrary key-value map merged or replaced per your API behavior — use for app-specific group attributes.

PATCH{baseUrl}/api/{apiVersion}/conversation/group/information/update

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <chat_user_token>	Chat user Bearer token for a participant allowed to edit group info (admin when `onlyAdminCanEditInfo` is true).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Request Payload

Example updating group name, description, avatar URL, and metadata:

json

{
  "conversationId": "694b...d8",
  "groupName": "Dev Team 2.0",
  "groupDescription": "Now with more sprints",
  "groupImage": "https://cdn.example.com/group-v2.png",
  "metadata": {
    "workspaceId": "c1"
  }
}

Success Response (HTTP 200 OK)

On success, data.conversation contains the updated group document. Refresh the SDK header, avatar, and info panel from these fields.

json

{
  "success": true,
  "message": "Group information updated successfully",
  "data": {
    "conversation": {
      "_id": "694b...d8",
      "conversationType": "group",
      "groupName": "Dev Team",
      "groupDescription": "Sprint coordination",
      "groupImage": null,
      "participants": [
        "694b...a1",
        "694b...a2",
        "694b...a3"
      ],
      "groupAdmins": [
        "694b...a3"
      ],
      "owner": "694b...a3",
      "groupPermissions": {
        "onlyAdminCanSendMessage": false,
        "onlyAdminCanEditInfo": false,
        "senderCanEditMessage": true,
        "allowMemberAdd": true,
        "allowMemberRemove": false,
        "moderationEnabled": false
      },
      "unreadCount": {},
      "pinnedMessage": [],
      "lastMessage": "70a1...c4",
      "metadata": {
        "workspaceId": "c1"
      },
      "createdAt": "2026-07-10T09:00:00.000Z",
      "updatedAt": "2026-07-10T09:00:00.000Z"
    }
  },
  "error": null
}

Common Errors

Information updates fail when the token is invalid, the conversation is missing, the caller cannot edit info, or no updatable fields were sent.

HTTP 401 Unauthorized — No token

json

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 403 Forbidden — Insufficient permissions

json

{
  "success": false,
  "message": "Access denied: insufficient permissions",
  "data": null,
  "error": null
}

HTTP 404 Not Found — Conversation missing

json

{
  "success": false,
  "message": "Conversation not found",
  "data": null,
  "error": null
}

HTTP 400 Bad Request — No fields to update

json

{
  "success": false,
  "message": "At least one field to update is required",
  "data": null,
  "error": null
}

Code	Reason
401 Unauthorized	Chat user token is missing, invalid, or expired.
403 Forbidden	Caller cannot edit group info (non-admin when `onlyAdminCanEditInfo` is true).
404 Not Found	No group conversation matches `conversationId`.
400 Bad Request	Empty body or no updatable fields besides `conversationId`.
500 Internal Server Error	An unexpected error occurred while updating group information.

Best Practices

Upload avatars to your own storage and pass a stable HTTPS URL in groupImage — do not send raw binary in this endpoint.
Send only changed fields to avoid accidental overwrites of description or metadata.
Check groupPermissions.onlyAdminCanEditInfo before showing edit controls to regular members.
Optimistically update the SDK UI, then reconcile with the response on success or roll back on error.

Group info updated

Refresh the conversation list title, header avatar, and group info screen from data.conversation. Use Group Permissions for behavior flags — this endpoint only updates display metadata.

Field

Type

Required

Description

conversationId

string

Required

The group conversation's _id.

groupName

string

Optional

New display name for the group in the SDK conversation list and header.

groupDescription

string

Optional

Updated description shown in group info screens.

groupImage

string

Optional

URL for the group avatar. Upload the image to your CDN or storage first, then pass the public URL here.

metadata

object

Optional

Arbitrary key-value map merged or replaced per your API behavior — use for app-specific group attributes.

Header

Value

Description

Authorization

Bearer <chat_user_token>

Chat user Bearer token for a participant allowed to edit group info (admin when onlyAdminCanEditInfo is true).

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Content-Type

application/json

JSON request body.

{ "conversationId": "694b...d8", "groupName": "Dev Team 2.0", "groupDescription": "Now with more sprints", "groupImage": "https://cdn.example.com/group-v2.png", "metadata": { "workspaceId": "c1" } }

{ "success": true, "message": "Group information updated successfully", "data": { "conversation": { "_id": "694b...d8", "conversationType": "group", "groupName": "Dev Team", "groupDescription": "Sprint coordination", "groupImage": null, "participants": [ "694b...a1", "694b...a2", "694b...a3" ], "groupAdmins": [ "694b...a3" ], "owner": "694b...a3", "groupPermissions": { "onlyAdminCanSendMessage": false, "onlyAdminCanEditInfo": false, "senderCanEditMessage": true, "allowMemberAdd": true, "allowMemberRemove": false, "moderationEnabled": false }, "unreadCount": {}, "pinnedMessage": [], "lastMessage": "70a1...c4", "metadata": { "workspaceId": "c1" }, "createdAt": "2026-07-10T09:00:00.000Z", "updatedAt": "2026-07-10T09:00:00.000Z" } }, "error": null }

Code

Reason

401 Unauthorized

Chat user token is missing, invalid, or expired.

403 Forbidden

Caller cannot edit group info (non-admin when onlyAdminCanEditInfo is true).

404 Not Found

No group conversation matches conversationId.

400 Bad Request

Empty body or no updatable fields besides conversationId.

500 Internal Server Error

An unexpected error occurred while updating group information.