Create Group Conversation

Overview

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.

When to use this endpoint?

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.

Workflow

1
Pick participants
In the chat SDK people picker, select chat user ids to include in the new group (excluding the creator, who is added automatically).
2
Set group details
Collect groupName, optional description, avatar URL, permissions, and any metadata your app needs.
3
Create the group
POST the payload with tenant headers and the signed-in chat user Bearer token. The API returns the full group conversation document.

Request Fields

Field	Type	Required	Description
participants	string[]	Required	Chat user ids to add to the group (excluding the creator, who is added automatically as owner and admin).
groupName	string	Required	Display name shown in the SDK conversation list and group header.
creator	string	Required	Chat user id of the person creating the group. Becomes `owner` and is included in `groupAdmins`.
groupDescription	string	Optional	Short description shown in group info screens.
groupImage	string	Optional	URL for the group avatar image.
groupPermissions	object	Optional	Permission flags for messaging, editing, and membership. See Group Permissions for each flag.
metadata	object	Optional	Arbitrary key-value map for app-specific attributes.

POST{baseUrl}/api/{apiVersion}/conversation/group/create

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 the signed-in participant creating the group.
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 creating a Dev Team group with two participants, a creator, default permissions, and workspace metadata:

json

1{2  "participants": [3    "694b...a1",4    "694b...a2"5  ],6  "groupName": "Dev Team",7  "creator": "694b...a3",8  "groupDescription": "Sprint coordination",9  "groupImage": "https://cdn.example.com/group.png",10  "groupPermissions": {11    "onlyAdminCanSendMessage": false,12    "onlyAdminCanEditInfo": false,13    "senderCanEditMessage": true,14    "allowMemberAdd": true,15    "allowMemberRemove": false,16    "moderationEnabled": false17  },18  "metadata": {19    "workspaceId": "c1"20  }21}

Success Response (HTTP 200 OK)

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

json

1{2  "success": true,3  "message": "Group conversation created 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      "isArchived": false,31      "lastMessage": "70a1...c4",32      "metadata": {33        "workspaceId": "c1"34      },35      "createdAt": "2026-07-10T09:00:00.000Z",36      "updatedAt": "2026-07-10T09:00:00.000Z"37    }38  },39  "error": null40}

Common Errors

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

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 400 Bad Request - Missing required fields

json

1{2  "success": false,3  "message": "participants and groupName are required",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Chat user token is missing, invalid, or expired.
403 Forbidden	Caller is not allowed to create group conversations.
400 Bad Request	Missing `participants`, `groupName`, or `creator`; invalid user ids.
500 Internal Server Error	An unexpected error occurred while creating the group.

Best Practices

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.

Group created

Open the new thread in the chat SDK using data.conversation._id. Use Group Participants or Group Admins to adjust membership after creation.

Create Group Conversation

Overview

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.

When to use this endpoint?

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.

Workflow

1
Pick participants
In the chat SDK people picker, select chat user ids to include in the new group (excluding the creator, who is added automatically).
2
Set group details
Collect groupName, optional description, avatar URL, permissions, and any metadata your app needs.
3
Create the group
POST the payload with tenant headers and the signed-in chat user Bearer token. The API returns the full group conversation document.

Request Fields

Field	Type	Required	Description
participants	string[]	Required	Chat user ids to add to the group (excluding the creator, who is added automatically as owner and admin).
groupName	string	Required	Display name shown in the SDK conversation list and group header.
creator	string	Required	Chat user id of the person creating the group. Becomes `owner` and is included in `groupAdmins`.
groupDescription	string	Optional	Short description shown in group info screens.
groupImage	string	Optional	URL for the group avatar image.
groupPermissions	object	Optional	Permission flags for messaging, editing, and membership. See Group Permissions for each flag.
metadata	object	Optional	Arbitrary key-value map for app-specific attributes.

POST{baseUrl}/api/{apiVersion}/conversation/group/create

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 the signed-in participant creating the group.
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 creating a Dev Team group with two participants, a creator, default permissions, and workspace metadata:

json

1{2  "participants": [3    "694b...a1",4    "694b...a2"5  ],6  "groupName": "Dev Team",7  "creator": "694b...a3",8  "groupDescription": "Sprint coordination",9  "groupImage": "https://cdn.example.com/group.png",10  "groupPermissions": {11    "onlyAdminCanSendMessage": false,12    "onlyAdminCanEditInfo": false,13    "senderCanEditMessage": true,14    "allowMemberAdd": true,15    "allowMemberRemove": false,16    "moderationEnabled": false17  },18  "metadata": {19    "workspaceId": "c1"20  }21}

Success Response (HTTP 200 OK)

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

json

1{2  "success": true,3  "message": "Group conversation created 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      "isArchived": false,31      "lastMessage": "70a1...c4",32      "metadata": {33        "workspaceId": "c1"34      },35      "createdAt": "2026-07-10T09:00:00.000Z",36      "updatedAt": "2026-07-10T09:00:00.000Z"37    }38  },39  "error": null40}

Common Errors

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

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 400 Bad Request - Missing required fields

json

1{2  "success": false,3  "message": "participants and groupName are required",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Chat user token is missing, invalid, or expired.
403 Forbidden	Caller is not allowed to create group conversations.
400 Bad Request	Missing `participants`, `groupName`, or `creator`; invalid user ids.
500 Internal Server Error	An unexpected error occurred while creating the group.

Best Practices

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.

Group created

Open the new thread in the chat SDK using data.conversation._id. Use Group Participants or Group Admins to adjust membership after creation.

Pick participants

Set group details

Create the group

HTTP 401 Unauthorized - No token

HTTP 403 Forbidden - Insufficient permissions

HTTP 400 Bad Request - Missing required fields

Group created

Pick participants

Set group details

Create the group

HTTP 401 Unauthorized - No token

HTTP 403 Forbidden - Insufficient permissions

HTTP 400 Bad Request - Missing required fields

Group created