> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-ios-ui-kit-sdk-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Join A Group

> Guide to joining public, private, and password-protected groups using the CometChat iOS SDK joinGroup method.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **Join group:** `CometChat.joinGroup(GUID:groupType:password:onSuccess:onError:)`
  * **Public groups:** No password required
  * **Password groups:** Password required
  * **Private groups:** Cannot join directly — must be added by admin/owner
  * **Related:** [Create Group](/sdk/ios/create-group) · [Leave Group](/sdk/ios/leave-group) · [Groups Overview](/sdk/ios/groups-overview)
</Info>

## Join a Group

In order to start participating in group conversations, you will have to join a group. You can do so using the `joinGroup()` method.

### Join Group Parameters

| Parameter | Type                         | Description                           |
| --------- | ---------------------------- | ------------------------------------- |
| GUID      | String                       | Unique group identifier               |
| groupType | [GroupType](#grouptype-enum) | `.public`, `.private`, or `.password` |
| password  | String?                      | Required for `.password` groups       |

### Group Type Behavior

| Type      | Can Join Directly | Password Required            |
| --------- | ----------------- | ---------------------------- |
| .public   | Yes               | No                           |
| .password | Yes               | Yes                          |
| .private  | No                | N/A (must be added by admin) |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let guid = "cometchat-guid-11"
    let password: String? = nil // mandatory in case of password protected group type

    CometChat.joinGroup(GUID: guid, groupType: .public, password: nil, onSuccess: { (group) in
        print("Group joined successfully. " + group.stringValue())
    }, onError: { (error) in
        print("Group joining failed with error:" + error!.errorDescription)
    })
    ```
  </Tab>

  <Tab title="Objective C">
    ```objc theme={null}
    NSString *guid = @"cometchat-guid-101";
    NSString *password = nil; // mandatory in case of password protected group type

    [CometChat joinGroupWithGUID:guid groupType:groupTypePublic password:password onSuccess:^(Group * group) {
        NSLog(@"Group joined successfully: %@", [group stringValue]);
    } onError:^(CometChatException * error) {
        NSLog(@"Group joining failed with exception: %@", [error errorDescription]);
    }];
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payload - Join Public Group">
  **Request Parameters:**

  | Parameter | Type                         | Description                                            |
  | --------- | ---------------------------- | ------------------------------------------------------ |
  | GUID      | String                       | Unique group identifier. Example: `"cometchat-guid-1"` |
  | groupType | [GroupType](#grouptype-enum) | Type of group. Example: `.public`                      |
  | password  | String?                      | Password for the group. Example: `nil`                 |

  **Success Response ([Group](/sdk/ios/retrieve-groups#group-properties) Object):**

  | Parameter        | Type                             | Description                                                                                                       |
  | ---------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
  | guid             | String                           | Unique group identifier. Example: `"cometchat-guid-1"`                                                            |
  | name             | String?                          | Group display name. Example: `"Hiking Group"`                                                                     |
  | groupType        | [GroupType](#grouptype-enum)     | Type of group. Example: `.public`                                                                                 |
  | icon             | String?                          | URL to the group's icon image. Example: `"https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp"` |
  | groupDescription | String?                          | Description of the group. Example: `"Explore, connect, and chat with fellow outdoor enthusiasts"`                 |
  | owner            | String?                          | UID of the group owner. Example: `"cometchat-uid-5"`                                                              |
  | membersCount     | Int                              | Total number of members (incremented by 1). Example: `6`                                                          |
  | hasJoined        | Bool                             | Whether the logged-in user is a member. Example: `true`                                                           |
  | joinedAt         | Int                              | Unix timestamp when user joined. Example: `1772113500`                                                            |
  | scope            | [MemberScope](#memberscope-enum) | User's scope in the group. Example: `.participant`                                                                |
  | createdAt        | Int                              | Unix timestamp when group was created. Example: `1753861429`                                                      |
  | tags             | \[String]                        | Array of tags. Example: `[]`                                                                                      |
  | metadata         | \[String: Any]?                  | Custom metadata dictionary. Example: `[:]`                                                                        |

  **Success Response Properties After Join:**

  | Property     | Value After Join | Description                   |
  | ------------ | ---------------- | ----------------------------- |
  | hasJoined    | true             | User is now a member          |
  | joinedAt     | Unix timestamp   | Time of joining               |
  | scope        | .participant     | Default scope for new members |
  | membersCount | Incremented by 1 | Updated member count          |

  **Error Response ([CometChatException](#common-error-codes)):**

  | Parameter        | Type   | Description                                                                       |
  | ---------------- | ------ | --------------------------------------------------------------------------------- |
  | errorCode        | String | Unique error code. Example: `"ERR_ALREADY_JOINED"`                                |
  | errorDescription | String | Human-readable error message. Example: `"User is already a member of this group"` |
</Accordion>

<Accordion title="Sample Payload - Join Password Group">
  **Request Parameters:**

  | Parameter | Type                         | Description                                             |
  | --------- | ---------------------------- | ------------------------------------------------------- |
  | GUID      | String                       | Unique group identifier. Example: `"cometchat-guid-1"`  |
  | groupType | [GroupType](#grouptype-enum) | Type of group. Example: `.password`                     |
  | password  | String                       | Password for the group (required). Example: `"test123"` |

  **Success Response ([Group](/sdk/ios/retrieve-groups#group-properties) Object):**

  | Parameter        | Type                             | Description                                                  |
  | ---------------- | -------------------------------- | ------------------------------------------------------------ |
  | guid             | String                           | Unique group identifier. Example: `"cometchat-guid-1"`       |
  | name             | String?                          | Group display name. Example: `"Secret Group"`                |
  | groupType        | [GroupType](#grouptype-enum)     | 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-5"`         |
  | membersCount     | Int                              | Total number of members. Example: `5`                        |
  | hasJoined        | Bool                             | Whether the logged-in user is a member. Example: `true`      |
  | joinedAt         | Int                              | Unix timestamp when user joined. Example: `1772113600`       |
  | scope            | [MemberScope](#memberscope-enum) | User's scope in the group. Example: `.participant`           |
  | createdAt        | Int                              | Unix timestamp when group was created. Example: `1753861429` |
  | tags             | \[String]                        | Array of tags. Example: `[]`                                 |
  | metadata         | \[String: Any]?                  | Custom metadata dictionary. Example: `[:]`                   |

  **Error Response - Wrong Password:**

  | Parameter        | Type   | Description                                                                                |
  | ---------------- | ------ | ------------------------------------------------------------------------------------------ |
  | errorCode        | String | Unique error code. Example: `"ERR_WRONG_GROUP_PASS"`                                       |
  | errorDescription | String | Human-readable error message. Example: `"Incorrect password for password-protected group"` |
</Accordion>

<Accordion title="Sample Payload - Join Private Group (Error)">
  **Request Parameters:**

  | Parameter | Type                         | Description                                            |
  | --------- | ---------------------------- | ------------------------------------------------------ |
  | GUID      | String                       | Unique group identifier. Example: `"cometchat-guid-1"` |
  | groupType | [GroupType](#grouptype-enum) | Type of group. Example: `.private`                     |
  | password  | String?                      | Password for the group. Example: `nil`                 |

  **Error Response:**

  | Parameter        | Type   | Description                                                                                                            |
  | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
  | errorCode        | String | Unique error code. Example: `"ERR_GROUP_JOIN_NOT_ALLOWED"`                                                             |
  | errorDescription | String | Human-readable error message. Example: `"The private groups cannot be joined. Users need to be added to such groups."` |

  <Warning>Private groups cannot be joined directly. Users must be added by an admin or owner.</Warning>
</Accordion>

Once you have joined a group successfully, you can send and receive messages in that group.

<Warning>
  CometChat keeps a track of the groups joined and you do not need to join the group every time you want to communicate in the group. You can identify if a group is joined using the `hasJoined` parameter in the `Group` object.
</Warning>

***

## Real-time Group Member Joined Events

*In other words, as a recipient, how do I know when someone joins a group?*

To receive Real-Time Events for the same, you need to implement the `onGroupMemberJoined()` method of the `CometChatGroupDelegate`.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    class ViewController: UIViewController, CometChatGroupDelegate {
        
        override func viewDidLoad() {
            super.viewDidLoad()
            CometChat.groupdelegate = self
        }
        
        func onGroupMemberJoined(action: ActionMessage, joinedUser: User, joinedGroup: Group) {
            print("\(joinedUser.name ?? "") joined \(joinedGroup.name ?? "")")
        }
        
        func onMemberAddedToGroup(action: ActionMessage, addedBy: User, addedUser: User, addedTo: Group) {
            print("\(addedUser.name ?? "") was added to \(addedTo.name ?? "")")
        }
    }
    ```
  </Tab>

  <Tab title="Objective C">
    ```objc theme={null}
    @interface ViewController ()<CometChatGroupDelegate>
    @end

    @implementation ViewController

    - (void)viewDidLoad {
        [super viewDidLoad];
        [CometChat setGroupdelegate:self];
    }

    - (void)onMemberAddedToGroup:(Action *)action addedBy:(User * _Nonnull)addedBy addedUser:(User * _Nonnull)addedUser addedTo:(Group * _Nonnull)addedTo {
        // When any member is added in the group this function will be called
    }

    @end
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payload - onGroupMemberJoined Event">
  **Event Trigger:** Received via `CometChatGroupDelegate.onGroupMemberJoined(action:joinedUser:joinedGroup:)`

  **ActionMessage Object:**

  | Parameter | Type                                               | Description                                                                      |
  | --------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
  | action    | String                                             | Action type. Example: `"joined"`                                                 |
  | actionBy  | [User](/sdk/ios/users-overview#user-properties)    | User who performed the action. Example: `{"uid": "user123", "name": "John"}`     |
  | actionFor | [Group](/sdk/ios/retrieve-groups#group-properties) | Group where action occurred. Example: `{"guid": "group123", "name": "My Group"}` |

  **joinedUser ([User](/sdk/ios/users-overview#user-properties) Object):**

  | Parameter | Type                                                  | Description                                                                 |
  | --------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
  | uid       | String?                                               | Unique identifier of the user who joined. Example: `"user123"`              |
  | name      | String?                                               | Display name of the user. Example: `"John Doe"`                             |
  | avatar    | String?                                               | URL to the user's avatar image. Example: `"https://example.com/avatar.png"` |
  | status    | [UserStatus](/sdk/ios/retrieve-users#userstatus-enum) | Current online status. Example: `.online`                                   |

  **joinedGroup ([Group](/sdk/ios/retrieve-groups#group-properties) Object):**

  | Parameter    | Type    | Description                                    |
  | ------------ | ------- | ---------------------------------------------- |
  | guid         | String  | Unique group identifier. Example: `"group123"` |
  | name         | String? | Group display name. Example: `"My Group"`      |
  | membersCount | Int     | Updated member count. Example: `16`            |
</Accordion>

## Missed Group Member Joined Events

*In other words, as a member of a group, how do I know if someone joins the group when my app is not running?*

When you retrieve the list of previous messages if a member has joined any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class.

For the group member joined event, in the `Action` object received, the following fields can help you get the relevant information:

| Field     | Value        | Description               |
| --------- | ------------ | ------------------------- |
| action    | `"joined"`   | Action type               |
| actionBy  | User object  | User who joined the group |
| actionFor | Group object | Group the user joined     |

***

## 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\_NOT\_FOUND          | Group does not exist           | Verify the GUID is correct            |
| ERR\_ALREADY\_JOINED           | Already a member of this group | No action needed                      |
| ERR\_WRONG\_GROUP\_PASS        | Incorrect password             | Provide correct password              |
| ERR\_GROUP\_JOIN\_NOT\_ALLOWED | Cannot join private group      | Request admin to add you              |
| ERR\_USER\_BANNED              | User is banned from group      | Contact group admin                   |