Group Participants

Add or remove participants on an existing group conversation. Set type to add or remove, and pass chat user ids in the participants array.

Who may add or remove members depends on groupPermissions.allowMemberAdd and allowMemberRemove — admins can typically manage membership regardless. The response returns the updated conversation document.

Use Group Participants when:

• A user adds contacts from the SDK people picker to an existing group.
• An admin or permitted member removes someone from the group.
• You sync membership after an org change (new hire joins the project channel).
• A user leaves the group (remove their own id with type: remove if your app supports self-removal).

Part of the Chat Conversation APIs for the chat package / SDK — not Platform → Conversations. Requires a chat user Bearer token with permission to modify membership on the group.

Add participants — invite users from the people picker:

{
  "conversationId": "694b...d8",
  "type": "add",
  "participants": [
    "694b...a4",
    "694b...a5"
  ]
}

Remove participants — remove one or more members from the group:

{
  "conversationId": "694b...d8",
  "type": "remove",
  "participants": [
    "694b...a4"
  ]
}

On success, data.conversation.participants reflects the updated membership. The success message varies by operation (for example "Members added successfully").

{
  "success": true,
  "message": "Members added 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
}

Participant changes fail when the token is invalid, the conversation is missing, the caller lacks membership privileges, or the payload is malformed.

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

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

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

{
  "success": false,
  "message": "type must be add or remove",
  "data": null,
  "error": null
}

• Respect allowMemberAdd and allowMemberRemove before showing people-picker or remove actions to non-admins.
• After adding members, notify them via your app or rely on SDK realtime updates so new participants see the thread.
• When removing the group owner, transfer ownership or demote via Group Admins first according to your product rules.
• Batch multiple ids in one request when inviting several people from the picker to reduce round trips.