> ## 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.

# Users

> Overview of CometChat iOS SDK user management including creating, retrieving, updating, and blocking users with real-time presence tracking.

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

  * **Create user:** `CometChat.createUser(user:apiKey:onSuccess:onError:)`
  * **Get user:** `CometChat.getUser(UID:onSuccess:onError:)`
  * **List users:** `UsersRequest.UsersRequestBuilder().build()` → `usersRequest.fetchNext(onSuccess:onError:)`
  * **Block/unblock:** `CometChat.blockUsers(_:onSuccess:onError:)`, `CometChat.unblockUsers(_:onSuccess:onError:)`
  * **Related:** [User Management](/sdk/ios/user-management) · [Retrieve Users](/sdk/ios/retrieve-users) · [Block Users](/sdk/ios/block-users)
</Info>

The primary aim for our users' functionality is to allow you to quickly retrieve and add users to CometChat.

You can begin with [user management](/sdk/ios/user-management) to sync your users to CometChat. Once that is done, you can [retrieve users](/sdk/ios/retrieve-users) and display them in your app.

***

## User Data Model

The `User` class represents a CometChat user with all their profile information.

### Creating a User Object

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    // Basic user creation
    let user = User(uid: "user123", name: "John Doe")

    // Set optional properties
    user.avatar = "https://example.com/avatar.png"
    user.link = "https://example.com/profile/user123"
    user.role = "default"
    user.metadata = ["department": "engineering", "level": 5]
    user.tags = ["premium", "verified"]
    ```
  </Tab>
</Tabs>

### User Properties

| Parameter     | Type                           | Editable | Description                                                                                           |
| ------------- | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| uid           | String?                        | No\*     | Unique user identifier. Must be alphanumeric with underscore/hyphen only. Required for user creation. |
| name          | String?                        | Yes      | Display name of the user. Required for user creation.                                                 |
| avatar        | String?                        | Yes      | URL to the user's avatar/profile image.                                                               |
| link          | String?                        | Yes      | URL to the user's profile page or external link.                                                      |
| role          | String?                        | Yes      | Role assigned to the user for role-based access control.                                              |
| metadata      | \[String: Any]?                | Yes      | Custom metadata dictionary for storing additional user information.                                   |
| status        | [UserStatus](#userstatus-enum) | No       | Current online status of the user: `.online` or `.offline`.                                           |
| statusMessage | String?                        | Yes      | Custom status message set by the user.                                                                |
| lastActiveAt  | Double                         | No       | Unix timestamp of the user's last activity.                                                           |
| hasBlockedMe  | Bool                           | No       | Indicates if this user has blocked the logged-in user.                                                |
| blockedByMe   | Bool                           | No       | Indicates if the logged-in user has blocked this user.                                                |
| deactivatedAt | Double                         | No       | Unix timestamp when user was deactivated. Value is `0.0` if user is active.                           |
| tags          | \[String]                      | Yes      | Array of tags for categorizing and filtering users.                                                   |

<Note>\* uid is specified on user creation and not editable after that</Note>

<Accordion title="Sample Payload - User Object">
  | Parameter           | Type                           | Description                                                                                               |
  | ------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------- |
  | uid                 | String?                        | Unique identifier of the user. 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"`                               |
  | link                | String?                        | URL to the user's profile page. Example: `"https://example.com/profile/user123"`                          |
  | role                | String?                        | Role assigned to the user for access control. Example: `"default"`                                        |
  | status              | [UserStatus](#userstatus-enum) | Current online status of the user. Example: `.online`                                                     |
  | statusMessage       | String?                        | Custom status message set by the user. Example: `"Available"`                                             |
  | lastActiveAt        | Double                         | Unix timestamp of the user's last activity. Example: `1699900000.0`                                       |
  | hasBlockedMe        | Bool                           | Indicates if this user has blocked the logged-in user. Example: `false`                                   |
  | blockedByMe         | Bool                           | Indicates if the logged-in user has blocked this user. Example: `false`                                   |
  | deactivatedAt       | Double                         | Unix timestamp when user was deactivated (0 if active). Example: `0.0`                                    |
  | tags                | \[String]                      | Array of tags associated with the user. Example: `["premium", "verified"]`                                |
  | metadata            | \[String: Any]?                | Custom metadata dictionary for additional user info. Example: `["department": "engineering", "level": 5]` |
  | metadata.department | String                         | Department the user belongs to (nested in metadata). Example: `"engineering"`                             |
  | metadata.level      | Int                            | User's level or rank (nested in metadata). Example: `5`                                                   |
</Accordion>

### UserStatus Enum

| Value    | Raw Value | Description                                             |
| -------- | --------- | ------------------------------------------------------- |
| .online  | 0         | User is currently online and active in the application. |
| .offline | 1         | User is currently offline or not connected.             |

### UID Requirements

| Rule               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| Alphanumeric       | Letters (a-z, A-Z) and numbers (0-9) are allowed       |
| Underscore         | Underscore character `_` is allowed                    |
| Hyphen             | Hyphen character `-` is allowed                        |
| Spaces             | Spaces are NOT allowed in UID                          |
| Punctuation        | Punctuation marks (., !, ?, etc.) are NOT allowed      |
| Special characters | Special characters (@, #, \$, %, etc.) are NOT allowed |

### Common Error Codes

| Error Code                | Description                                         | Resolution                                                |
| ------------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| ERR\_UID\_NOT\_FOUND      | User with specified UID does not exist in CometChat | Verify the UID is correct and the user has been created   |
| ERR\_USER\_DEACTIVATED    | User account has been deactivated                   | Contact admin to reactivate the user account              |
| ERR\_NOT\_LOGGED\_IN      | No user is currently logged in to CometChat         | Call `CometChat.login()` before performing this operation |
| ERR\_UID\_ALREADY\_EXISTS | User with specified UID already exists              | Use a different unique UID for the new user               |
| ERR\_INVALID\_API\_KEY    | The provided API key is invalid or expired          | Verify API key from CometChat Dashboard                   |
| ERR\_INVALID\_UID         | UID contains invalid characters                     | Use only alphanumeric characters, underscore, and hyphen  |
| ERR\_EMPTY\_UID           | UID is empty or null                                | Provide a valid non-empty UID                             |
| ERR\_EMPTY\_NAME          | Name is empty or null                               | Provide a valid non-empty name                            |
| ERR\_INVALID\_LIMIT       | Invalid limit value provided for pagination         | Use a limit value between 1 and 100                       |