Create Group Conversation

Create a new group conversation in your chat app. The creator becomes the group owner and first admin; selected participants are added alongside them. You can set the group name, description, avatar, permission flags, and optional metadata in a single request.

On success, data.conversation is the full group document — use its _id to open the thread in the SDK, send messages, or manage members later.

Use Create Group Conversation when:

• A user taps "New group" in the chat SDK and picks contacts from the people picker.
• You need a multi-participant thread (team channel, project room, support desk group).
• You want to seed default permission flags (groupPermissions) at creation time.
• You attach app-specific context in metadata (workspace id, external room id, and so on).

Part of the Chat Conversation APIs for the chat package / SDK — not Platform → Conversations. Requires a signed-in chat user Bearer token, not a Platform client Access Token.

Example creating a Dev Team group with two participants, a creator, default permissions, and workspace metadata:

{
  "participants": [
    "694b...a1",
    "694b...a2"
  ],
  "groupName": "Dev Team",
  "creator": "694b...a3",
  "groupDescription": "Sprint coordination",
  "groupImage": "https://cdn.example.com/group.png",
  "groupPermissions": {
    "onlyAdminCanSendMessage": false,
    "onlyAdminCanEditInfo": false,
    "senderCanEditMessage": true,
    "allowMemberAdd": true,
    "allowMemberRemove": false,
    "moderationEnabled": false
  },
  "metadata": {
    "workspaceId": "c1"
  }
}

On success, the API returns the created group conversation. The creator is included in participants and groupAdmins, and set as owner.

{
  "success": true,
  "message": "Group conversation created 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": [],
      "isArchived": false,
      "lastMessage": "70a1...c4",
      "metadata": {
        "workspaceId": "c1"
      },
      "createdAt": "2026-07-10T09:00:00.000Z",
      "updatedAt": "2026-07-10T09:00:00.000Z"
    }
  },
  "error": null
}

Create fails when the chat user token is missing or invalid, required fields are absent, or the caller lacks permission to create groups.

{
  "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": "participants and groupName are required",
  "data": null,
  "error": null
}

• Pass the signed-in user's id as creator — do not rely on the token alone to infer ownership.
• Exclude the creator from participants to avoid duplicate entries; the API adds them automatically.
• Set sensible default groupPermissions at create time so the SDK UI matches your product rules from the first message.
• Store the returned conversation._id in your chat state and navigate the SDK to that thread immediately after create.