Create A Group

Quick Reference for AI Agents & Developers

Create group: Group(guid:name:groupType:password:) → CometChat.createGroup(group:onSuccess:onError:)
Create with members: CometChat.createGroupWithMembers(group:members:banMembers:onSuccess:onError:)
Group types: .public, .private, .password
Required fields: GUID, name, groupType
Optional: password (required for .password type), icon, description, metadata, tags
Related: Join Group · Retrieve Groups · Groups Overview

Group Class

The Group class represents a CometChat group with all its properties.

Group Initializers

Initializer	Description
`Group(guid:name:groupType:password:)`	Basic initializer
`Group(guid:name:groupType:password:icon:description:)`	Full initializer

Swift

// Basic Initializer
let group = Group(guid: "group123", name: "My Group", groupType: .public, password: nil)

// Full Initializer
let group = Group(guid: "group123", name: "My Group", groupType: .password, password: "secret123", icon: "https://example.com/icon.png", description: "A test group")

Group Properties

Property	Type	Editable	Description
guid	String	No*	Unique group identifier
name	String?	Yes	Group display name
groupType	GroupType	No	`.public`, `.private`, `.password`
password	String?	No	Password (for `.password` type)
icon	String?	Yes	Group icon URL
groupDescription	String?	Yes	Group description
owner	String?	Yes	UID of group owner
metadata	[String: Any]?	Yes	Custom metadata dictionary
createdAt	Int	No	Creation Unix timestamp
updatedAt	Int	No	Last update Unix timestamp
hasJoined	Bool	No	Is logged-in user a member
joinedAt	Int	No	When user joined (timestamp)
membersCount	Int	No	Total number of members
scope	MemberScope	Yes	User’s scope in group
tags	[String]	Yes	Array of group tags

* guid is specified at creation and cannot be edited later

Sample Payload - Group Object

Group Object Properties:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-public-1772113094"`
name	String?	Group display name. Example: `"Test Public Group"`
groupType	GroupType	Type of group. Example: `.public`
icon	String?	URL to the group’s icon image. Example: `nil`
groupDescription	String?	Description of the group. Example: `nil`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113095`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113094`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Creator is automatically assigned .admin scope with hasJoined = true

GUID Requirements

Requirement	Description
Alphanumeric	Letters and numbers allowed
Underscore	`_` allowed
Hyphen	`-` allowed
Spaces	NOT allowed
Punctuation	NOT allowed
Special characters	NOT allowed

In other words, as a logged-in user, how do I create a public, private or password-protected group? You can create a group using createGroup() method. This method takes a Group object as a parameter.

Swift
Objective C

let guid = "cometchat-guid-11"
let groupName = "TestGroup1"
let password = "" // mandatory in case of password protected group type

let group = Group(guid: guid, name: groupName, groupType: .private, password: password)

CometChat.createGroup(group: group, onSuccess: { (group) in
    print("Group created successfully. " + group.stringValue())
}, onError: { (error) in
    print("Group creation failed with error:" + error!.errorDescription)
})

NSString *guid = @"cometchat-guid-101";
NSString *name = @"TestGroup1";
NSString *password = nil; // mandatory in case of password protected group type

Group *group = [[Group alloc]initWithGuid:guid name:name groupType:groupTypePublic password:password];

[CometChat createGroupWithGroup:group onSuccess:^(Group * group) {
    NSLog(@"Group created successfully. %@", [group stringValue]);
} onError:^(CometChatException * error) {
    NSLog(@"Group creation failed with error: %@", [error errorDescription]);
}];

Parameter	Description
group	An instance of `Group` class

GUID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed.

Sample Payload - Create Public Group

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-public-1772113094"`
name	String	Group display name. Example: `"Test Public Group"`
groupType	GroupType	Type of group. Example: `.public`
password	String?	Password for the group. Example: `nil`

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-public-1772113094"`
name	String?	Group display name. Example: `"Test Public Group"`
groupType	GroupType	Type of group. Example: `.public`
icon	String?	URL to the group’s icon image. Example: `nil`
groupDescription	String?	Description of the group. Example: `nil`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113095`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113094`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Creator is automatically admin with hasJoined = true

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: `"ERR_GUID_ALREADY_EXISTS"`
errorDescription	String	Human-readable error message. Example: `"Group with this GUID already exists"`

Sample Payload - Create Private Group

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-private-1772113095"`
name	String	Group display name. Example: `"Test Private Group"`
groupType	GroupType	Type of group. Example: `.private`
password	String?	Password for the group. Example: `nil`

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-private-1772113095"`
name	String?	Group display name. Example: `"Test Private Group"`
groupType	GroupType	Type of group. Example: `.private`
icon	String?	URL to the group’s icon image. Example: `nil`
groupDescription	String?	Description of the group. Example: `nil`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113095`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113095`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Private groups require invitation to join. Creator is automatically admin.

Sample Payload - Create Password Group

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-password-1772113096"`
name	String	Group display name. Example: `"Test Password Group"`
groupType	GroupType	Type of group. Example: `.password`
password	String	Password for the group (required). Example: `"test123"`

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-password-1772113096"`
name	String?	Group display name. Example: `"Test Password Group"`
groupType	GroupType	Type of group. Example: `.password`
icon	String?	URL to the group’s icon image. Example: `nil`
groupDescription	String?	Description of the group. Example: `nil`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113096`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113096`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Password is required for .password type groups. Creator is automatically admin.

Sample Payload - Create Group with Details

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-detailed-1772113098"`
name	String	Group display name. Example: `"Detailed Group"`
groupType	GroupType	Type of group. Example: `.public`
password	String?	Password for the group. Example: `nil`
icon	String?	URL to the group’s icon image. Example: `"https://example.com/icon.png"`
description	String?	Description of the group. Example: `"A test group with details"`

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-detailed-1772113098"`
name	String?	Group display name. Example: `"Detailed Group"`
groupType	GroupType	Type of group. Example: `.public`
icon	String?	URL to the group’s icon image. Example: `"https://example.com/icon.png"`
groupDescription	String?	Description of the group. Example: `"A test group with details"`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113098`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113098`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Sample Payload - Create Group with Metadata

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-metadata-1772113100"`
name	String	Group display name. Example: `"Metadata Group"`
groupType	GroupType	Type of group. Example: `.public`
metadata	[String: Any]	Custom metadata dictionary. Example: `["priority": 1, "category": "test"]`
tags	[String]	Array of tags. Example: `["test", "debug"]`

Metadata Properties:

Parameter	Type	Description
metadata.priority	Int	Priority level of the group. Example: `1`
metadata.category	String	Category of the group. Example: `"test"`

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-metadata-1772113100"`
name	String?	Group display name. Example: `"Metadata Group"`
groupType	GroupType	Type of group. Example: `.public`
icon	String?	URL to the group’s icon image. Example: `nil`
groupDescription	String?	Description of the group. Example: `nil`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`
membersCount	Int	Total number of members. Example: `1`
hasJoined	Bool	Whether the logged-in user is a member. Example: `true`
joinedAt	Int	Unix timestamp when user joined. Example: `1772113100`
scope	MemberScope	User’s scope in the group. Example: `.admin`
createdAt	Int	Unix timestamp when group was created. Example: `1772113100`
updatedAt	Int	Unix timestamp of last update. Example: `0`
tags	[String]	Array of tags. Example: `["test", "debug"]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `["category": "test", "priority": 1]`

Add Members While Creating a Group

You can create a group and add members at the same time using the createGroupWithMembers() method. This method takes the Group Object, Array of GroupMember Objects to be added & Array of UIDs to be banned.

GroupMember Class

Initializer	Description
`GroupMember(UID:groupMemberScope:)`	Create a group member with UID and scope

Swift

// Create group member objects
let member = GroupMember(UID: "user123", groupMemberScope: .participant)

// With different scopes
let admin = GroupMember(UID: "admin-user", groupMemberScope: .admin)
let moderator = GroupMember(UID: "mod-user", groupMemberScope: .moderator)
let participant = GroupMember(UID: "regular-user", groupMemberScope: .participant)

Swift

let group = Group(guid: "cometchat-uid-group1", name: "Hello Group", groupType: .public, password: nil)

let members = [
    GroupMember(UID: "cometchat-uid-4", groupMemberScope: .participant)
]

let banMembers = ["cometchat-uid-2"]

CometChat.createGroupWithMembers(group: group, members: members, banMembers: banMembers, onSuccess: { response in
    print("Group created successfully", response)
}, onError: { (error) in
    print("Error: \(String(describing: error?.errorDescription))")
})

Sample Payload - Create Group with Members

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-members-1772113101"`
name	String	Group display name. Example: `"Group with Members"`
groupType	GroupType	Type of group. Example: `.public`
members	[GroupMember]	Array of members to add. Example: `1 member`
banMembers	[String]	Array of UIDs to ban. Example: `[]`

Members to Add:

UID	Scope	Description
cometchat-uid-2	.participant	Regular member with basic permissions

Success Response ([String: Any] Dictionary):

Parameter	Type	Description
group	Group	The created group object
members	[GroupMember]	Array of successfully added members
errors	[String: Any]	Any errors for specific members

Response - Created Group:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"test-members-1772113101"`
name	String?	Group display name. Example: `"Group with Members"`
membersCount	Int	Total number of members. Example: `2`
owner	String?	UID of the group owner. Example: `"cometchat-uid-2"`

Response - Added Members:

UID	Scope	Status
cometchat-uid-2	.participant	Added successfully

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: `"ERR_GUID_ALREADY_EXISTS"`
errorDescription	String	Human-readable error message. Example: `"Group with this GUID already exists"`

GroupType Enum

Value	Description
.public	Anyone can join without approval
.private	Requires invitation or approval to join
.password	Requires password to join

MemberScope Enum

Value	Description
.admin	Full control over group
.moderator	Can manage members and messages
.participant	Regular member with basic permissions

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Login first using `CometChat.login()`
ERR_GUID_ALREADY_EXISTS	Group with GUID already exists	Use a unique GUID
ERR_INVALID_GUID	Invalid GUID format	Use alphanumeric with underscore/hyphen only
ERR_EMPTY_GROUP_NAME	Group name is empty	Provide a valid group name
ERR_INVALID_GROUP_TYPE	Invalid group type	Use `.public`, `.private`, or `.password`
ERR_PASSWORD_MISSING	Password required for password group	Provide password for `.password` type

​Group Class

​Group Initializers

​Group Properties

​GUID Requirements

​Create a Group

​Add Members While Creating a Group

​GroupMember Class

​GroupType Enum

​MemberScope Enum

​Common Error Codes

Group Class

Group Initializers

Group Properties

GUID Requirements

Create a Group

Add Members While Creating a Group

GroupMember Class

GroupType Enum

MemberScope Enum

Common Error Codes