Group Permission

Overview

Update permission flags on a group conversation. Flags control who can send messages, edit group info, modify messages, add or remove members, and whether moderation is enabled - the SDK should read these values to show or hide actions in the group settings and composer.

Send the full groupPermissions object with the desired boolean values. The response returns the updated conversation document.

When to use this endpoint?

Use Group Permissions when:

A group admin toggles "Only admins can send messages" in the SDK settings panel.
You switch a broadcast-style group to read-only for regular members.
You enable or disable member self-service add/remove from the people picker.
You turn on moderation for a moderated community channel.

Part of the Chat Conversation APIs for the chat package / SDK — not Platform → Conversations. Requires a chat user Bearer token with admin privileges on the group (subject to onlyAdminCanEditInfo).

Request Fields

Field	Type	Required	Description
conversationId	string	Required	The group conversation's `_id`.
groupPermissions	object	Required	Boolean flags that define group behavior. See the permission flags table below.

Permission Flags

Each key inside groupPermissions controls a specific capability in the chat SDK:

Flag	When true	SDK impact
onlyAdminCanSendMessage	Only group admins may send new messages.	Hide or disable the message composer for non-admin members; useful for announcement channels.
onlyAdminCanEditInfo	Only admins may change group name, description, image, or permissions.	Restrict group settings and permission toggles to admins in the SDK UI.
senderCanEditMessage	Message senders may edit their own messages after sending.	Show an edit action on the sender's messages; hide it when false.
allowMemberAdd	Regular members (not only admins) may add participants.	Expose "Add people" in the SDK to all members when true; admin-only when false.
allowMemberRemove	Regular members may remove other participants (within policy).	Allow member-initiated removals from the participant list; admins can typically always remove members.
moderationEnabled	Moderation features are active for this group.	Enable moderation workflows (review, flag, or restrict content) according to your SDK implementation.

PATCH{baseUrl}/api/{apiVersion}/conversation/group/permission/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 group admin or owner.
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 all permission flags for a group conversation:

json

1{2  "conversationId": "694b...d8",3  "groupPermissions": {4    "onlyAdminCanSendMessage": false,5    "onlyAdminCanEditInfo": false,6    "senderCanEditMessage": true,7    "allowMemberAdd": true,8    "allowMemberRemove": false,9    "moderationEnabled": false10  }11}

Success Response (HTTP 200 OK)

On success, data.conversation.groupPermissions reflects the new flag values. Sync these in the SDK immediately so composers and settings menus match server state.

json

1{2  "success": true,3  "message": "Group conversation permissions updated successfully",4  "data": {5    "conversation": {6      "_id": "694b...d8",7      "conversationType": "group",8      "groupName": "Dev Team",9      "groupDescription": "Sprint coordination",10      "groupImage": null,11      "participants": [12        "694b...a1",13        "694b...a2",14        "694b...a3"15      ],16      "groupAdmins": [17        "694b...a3"18      ],19      "owner": "694b...a3",20      "groupPermissions": {21        "onlyAdminCanSendMessage": false,22        "onlyAdminCanEditInfo": false,23        "senderCanEditMessage": true,24        "allowMemberAdd": true,25        "allowMemberRemove": false,26        "moderationEnabled": false27      },28      "unreadCount": {},29      "pinnedMessage": [],30      "lastMessage": "70a1...c4",31      "metadata": {32        "workspaceId": "c1"33      },34      "createdAt": "2026-07-10T09:00:00.000Z",35      "updatedAt": "2026-07-10T09:00:00.000Z"36    }37  },38  "error": null39}

Common Errors

Permission updates fail when the token is invalid, the conversation is missing, the caller is not an admin, or the payload is incomplete.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Insufficient permissions

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Conversation missing

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

HTTP 400 Bad Request - Missing groupPermissions

json

1{2  "success": false,3  "message": "groupPermissions object is required",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Error: locked by workspace admin

json

1{2  "success": false,3  "message": "These permissions are locked by your workspace admin: onlyAdminCanSendMessage",4  "data": null,5  "error": ["onlyAdminCanSendMessage"]6}

Code	Reason
401 Unauthorized	Chat user token is missing, invalid, or expired.
403 Forbidden	Caller is not a group admin, or `onlyAdminCanEditInfo` blocks the change.
404 Not Found	No group conversation matches `conversationId`.
400 Bad Request	Missing or malformed `groupPermissions` object.
500 Internal Server Error	An unexpected error occurred while updating permissions.

Best Practices

Send all six flags in each update so the server state stays predictable - merge current values in your SDK before PATCHing.
Reflect onlyAdminCanSendMessage in the composer immediately; do not rely on failed send attempts alone.
Pair permission changes with UI copy so members understand why actions were disabled.
Set conservative defaults at group create time via Create Group Conversation, then adjust here as needed.

Permissions updated

Re-read groupPermissions from the response and refresh SDK toggles, the message composer, and member management actions accordingly.

Group Permission

Overview

Send the full groupPermissions object with the desired boolean values. The response returns the updated conversation document.

When to use this endpoint?

Use Group Permissions when:

A group admin toggles "Only admins can send messages" in the SDK settings panel.
You switch a broadcast-style group to read-only for regular members.
You enable or disable member self-service add/remove from the people picker.
You turn on moderation for a moderated community channel.

Request Fields

Field	Type	Required	Description
conversationId	string	Required	The group conversation's `_id`.
groupPermissions	object	Required	Boolean flags that define group behavior. See the permission flags table below.

Permission Flags

Each key inside groupPermissions controls a specific capability in the chat SDK:

Flag	When true	SDK impact
onlyAdminCanSendMessage	Only group admins may send new messages.	Hide or disable the message composer for non-admin members; useful for announcement channels.
onlyAdminCanEditInfo	Only admins may change group name, description, image, or permissions.	Restrict group settings and permission toggles to admins in the SDK UI.
senderCanEditMessage	Message senders may edit their own messages after sending.	Show an edit action on the sender's messages; hide it when false.
allowMemberAdd	Regular members (not only admins) may add participants.	Expose "Add people" in the SDK to all members when true; admin-only when false.
allowMemberRemove	Regular members may remove other participants (within policy).	Allow member-initiated removals from the participant list; admins can typically always remove members.
moderationEnabled	Moderation features are active for this group.	Enable moderation workflows (review, flag, or restrict content) according to your SDK implementation.

PATCH{baseUrl}/api/{apiVersion}/conversation/group/permission/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 group admin or owner.
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 all permission flags for a group conversation:

json

1{2  "conversationId": "694b...d8",3  "groupPermissions": {4    "onlyAdminCanSendMessage": false,5    "onlyAdminCanEditInfo": false,6    "senderCanEditMessage": true,7    "allowMemberAdd": true,8    "allowMemberRemove": false,9    "moderationEnabled": false10  }11}

Success Response (HTTP 200 OK)

On success, data.conversation.groupPermissions reflects the new flag values. Sync these in the SDK immediately so composers and settings menus match server state.

json

1{2  "success": true,3  "message": "Group conversation permissions updated successfully",4  "data": {5    "conversation": {6      "_id": "694b...d8",7      "conversationType": "group",8      "groupName": "Dev Team",9      "groupDescription": "Sprint coordination",10      "groupImage": null,11      "participants": [12        "694b...a1",13        "694b...a2",14        "694b...a3"15      ],16      "groupAdmins": [17        "694b...a3"18      ],19      "owner": "694b...a3",20      "groupPermissions": {21        "onlyAdminCanSendMessage": false,22        "onlyAdminCanEditInfo": false,23        "senderCanEditMessage": true,24        "allowMemberAdd": true,25        "allowMemberRemove": false,26        "moderationEnabled": false27      },28      "unreadCount": {},29      "pinnedMessage": [],30      "lastMessage": "70a1...c4",31      "metadata": {32        "workspaceId": "c1"33      },34      "createdAt": "2026-07-10T09:00:00.000Z",35      "updatedAt": "2026-07-10T09:00:00.000Z"36    }37  },38  "error": null39}

Common Errors

Permission updates fail when the token is invalid, the conversation is missing, the caller is not an admin, or the payload is incomplete.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Insufficient permissions

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Conversation missing

json

1{2  "success": false,3  "message": "Conversation not found",4  "data": null,5  "error": null6}

HTTP 400 Bad Request - Missing groupPermissions

json

1{2  "success": false,3  "message": "groupPermissions object is required",4  "data": null,5  "error": null6}

HTTP 403 Forbidden - Error: locked by workspace admin

json

1{2  "success": false,3  "message": "These permissions are locked by your workspace admin: onlyAdminCanSendMessage",4  "data": null,5  "error": ["onlyAdminCanSendMessage"]6}

Code	Reason
401 Unauthorized	Chat user token is missing, invalid, or expired.
403 Forbidden	Caller is not a group admin, or `onlyAdminCanEditInfo` blocks the change.
404 Not Found	No group conversation matches `conversationId`.
400 Bad Request	Missing or malformed `groupPermissions` object.
500 Internal Server Error	An unexpected error occurred while updating permissions.

Best Practices

Send all six flags in each update so the server state stays predictable - merge current values in your SDK before PATCHing.
Reflect onlyAdminCanSendMessage in the composer immediately; do not rely on failed send attempts alone.
Pair permission changes with UI copy so members understand why actions were disabled.
Set conservative defaults at group create time via Create Group Conversation, then adjust here as needed.

Permissions updated

Re-read groupPermissions from the response and refresh SDK toggles, the message composer, and member management actions accordingly.