> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Kit Builder Settings

> Comprehensive reference for all CometChatBuilderSettings options in the iOS UI Kit Builder.

The `CometChatBuilderSettings` object controls everything the iOS UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This object is loaded from your `cometchat-builder-settings.json` configuration file.

<Info>
  **For developers customizing their chat UI**: Edit `cometchat-builder-settings.json` to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/ios/integration) for setup.
</Info>

## Top-level Structure

The `CometChatBuilderSettings` object in Swift follows this structure:

```swift theme={null}
CometChatBuilderSettings.shared.chatFeatures
CometChatBuilderSettings.shared.callFeatures
CometChatBuilderSettings.shared.layout
CometChatBuilderSettings.shared.style
```

***

<Tip>
  All boolean settings follow the same pattern: `true` enables the feature and shows its UI elements, `false` hides them completely.
</Tip>

## 1. Chat Features (`chatFeatures`)

### 1.1 Core Messaging Experience (`coreMessagingExperience`)

Essential messaging features: typing indicators, media sharing, message actions, and presence.

| Setting                                                               | Type    | What It Does                                                                        |
| --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| Typing indicator (`typingIndicator`)                                  | boolean | Shows "typing..." indicator when someone is composing a message                     |
| Thread conversation & replies (`threadConversationAndReplies`)        | boolean | Enables threaded replies to specific messages, creating nested conversation threads |
| Photos sharing (`photosSharing`)                                      | boolean | Allows users to share images from device or camera                                  |
| Video sharing (`videoSharing`)                                        | boolean | Allows users to share video files                                                   |
| Audio sharing (`audioSharing`)                                        | boolean | Allows users to share audio files (mp3, wav, etc.)                                  |
| File sharing (`fileSharing`)                                          | boolean | Allows users to share documents (PDF, DOC, etc.)                                    |
| Edit messages (`editMessage`)                                         | boolean | Lets users modify their sent messages; edited messages show "(edited)" label        |
| Delete messages (`deleteMessage`)                                     | boolean | Lets users remove their sent messages                                               |
| Message delivery and read receipts (`messageDeliveryAndReadReceipts`) | boolean | Shows delivery (✓) and read (✓✓) status indicators on messages                      |
| User & friends presence (`userAndFriendsPresence`)                    | boolean | Shows online/offline status dot next to user avatars                                |
| Conversation and Advanced Search (`conversationAndAdvancedSearch`)    | boolean | Enables search across messages, users, and conversations                            |
| Moderation (`moderation`)                                             | boolean | Enables blocked message feedback for messages blocked by moderation rules           |
| Quoted Replies (`quotedReplies`)                                      | boolean | Lets users quote a message when replying, showing the original above their response |
| Mark as Unread (`markAsUnread`)                                       | boolean | Lets users mark a conversation as unread to revisit later                           |

### 1.2 Deeper User Engagement (`deeperUserEngagement`)

Interactive features: mentions, reactions, polls, voice notes, and collaborative tools.

| Setting                                              | Type    | What It Does                                                                                |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| Mentions (`mentions`)                                | boolean | Lets users @mention specific people in a message to notify them                             |
| Mention All (`mentionAll`)                           | boolean | Lets users type @all to notify every member in a group chat                                 |
| Reactions (`reactions`)                              | boolean | Lets users add emoji reactions (👍 ❤️ 😂 etc.) to messages                                  |
| Message Translation (`messageTranslation`)           | boolean | Translates messages to user's preferred language. Requires Dashboard setup                  |
| Polls (`polls`)                                      | boolean | Lets users create polls with multiple options for group voting. Requires Dashboard setup    |
| Collaborative Whiteboard (`collaborativeWhiteboard`) | boolean | Opens a shared whiteboard for real-time drawing and collaboration. Requires Dashboard setup |
| Collaborative Document (`collaborativeDocument`)     | boolean | Creates shared documents for real-time collaborative editing. Requires Dashboard setup      |
| Voice Notes (`voiceNotes`)                           | boolean | Lets users record and send voice messages                                                   |
| Emojis (`emojis`)                                    | boolean | Shows emoji picker in composer for browsing and inserting emojis                            |
| Stickers (`stickers`)                                | boolean | Lets users send sticker images from available packs. Requires Dashboard setup               |
| User Info (`userInfo`)                               | boolean | Lets users tap on another user's avatar to view their profile                               |
| Group Info (`groupInfo`)                             | boolean | Lets users tap on group header to view group details and member list                        |

### 1.3 AI User Copilot (`aiUserCopilot`)

AI-powered features to help users start and navigate conversations.

| Setting                                      | Type    | What It Does                                                                                  |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| Conversation Starter (`conversationStarter`) | boolean | Shows AI-suggested opening messages when starting a new chat. Requires OpenAI API key         |
| Conversation Summary (`conversationSummary`) | boolean | Generates an AI-powered summary of the conversation. Requires OpenAI API key                  |
| Smart Reply (`smartReply`)                   | boolean | Shows AI-suggested quick reply options based on conversation context. Requires OpenAI API key |

<Tip>
  AI User Copilot features require an OpenAI API key. Configure it in the [CometChat Dashboard](https://app.cometchat.com) under **AI > Settings**.
</Tip>

### 1.4 User Management (`userManagement`)

| Setting                      | Type    | What It Does                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------- |
| Friends Only (`friendsOnly`) | boolean | Restricts chat to friends list only; Users tab shows only friends |

### 1.5 Group Management (`groupManagement`)

Control what users can do with groups.

| Setting                                      | Type    | What It Does                                                      |
| -------------------------------------------- | ------- | ----------------------------------------------------------------- |
| Create Group (`createGroup`)                 | boolean | Lets users create new public or private groups                    |
| Add Members to Groups (`addMembersToGroups`) | boolean | Lets group admins/owners invite users to join the group           |
| Join/Leave Group (`joinLeaveGroup`)          | boolean | Lets users join public groups and leave groups they're in         |
| Delete Group (`deleteGroup`)                 | boolean | Lets group owners permanently delete a group and all its messages |
| View Group Members (`viewGroupMembers`)      | boolean | Shows member list in group info                                   |

### 1.6 Moderator Controls (`moderatorControls`)

Admin tools for managing group members and content.

| Setting                                         | Type    | What It Does                                                           |
| ----------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| Report Message (`reportMessage`)                | boolean | Lets users flag messages for moderator review in Dashboard             |
| Kick Users (`kickUsers`)                        | boolean | Lets admins/moderators remove a user from a group (they can rejoin)    |
| Ban Users (`banUsers`)                          | boolean | Lets admins/moderators permanently remove a user and prevent rejoining |
| Promote/Demote Members (`promoteDemoteMembers`) | boolean | Lets group owners change member roles (member, moderator, admin)       |

### 1.7 Private Messaging Within Groups (`privateMessagingWithinGroups`)

Allow direct messages between group members.

| Setting                                                                    | Type    | What It Does                                                       |
| -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| Send Private Message to Group Members (`sendPrivateMessageToGroupMembers`) | boolean | Lets users start a 1:1 chat with a group member from their profile |

### 1.8 In-App Sounds (`inAppSounds`)

Control sound notifications for incoming and outgoing messages.

| Setting                                         | Type    | What It Does                                 |
| ----------------------------------------------- | ------- | -------------------------------------------- |
| Incoming Message Sound (`incomingMessageSound`) | boolean | Plays a sound when a new message is received |
| Outgoing Message Sound (`outgoingMessageSound`) | boolean | Plays a sound when a message is sent         |

***

## 2. Call Features (`callFeatures`)

### 2.1 Voice and Video Calling (`voiceAndVideoCalling`)

Enable voice and video calling capabilities.

| Setting                                         | Type    | What It Does                                                                |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| 1:1 Voice Calling (`oneOnOneVoiceCalling`)      | boolean | Shows phone icon in 1:1 chat header for starting voice calls                |
| 1:1 Video Calling (`oneOnOneVideoCalling`)      | boolean | Shows video camera icon in 1:1 chat header for starting video calls         |
| Group Video Conference (`groupVideoConference`) | boolean | Shows video camera icon in group chat header for starting group video calls |
| Group Voice Conference (`groupVoiceConference`) | boolean | Shows phone icon in group chat header for starting group voice calls        |

***

## 3. Layout (`layout`)

Control the overall UI structure and navigation.

| Setting                      | Type      | What It Does                                                                         |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
| With Sidebar (`withSideBar`) | boolean   | Shows navigation bar with tabs (Chats, Calls, Users, Groups)                         |
| Tabs (`tabs`)                | string\[] | Array of tabs to show: `'chats'`, `'calls'`, `'users'`, `'groups'`                   |
| Chat Type (`chatType`)       | string    | Default conversation type on load: `'user'` for 1:1 chats, `'group'` for group chats |

***

## 4. Style (`style`)

Customize colors, fonts, and theme appearance.

### 4.1 Theme

| Setting         | Type   | What It Does                                                                             |
| --------------- | ------ | ---------------------------------------------------------------------------------------- |
| Theme (`theme`) | string | Controls light/dark mode: `'light'`, `'dark'`, or `'system'` (matches device preference) |

### 4.2 Colors

| Setting                                     | Type   | What It Does                                                                             |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Brand Color (`brandColor`)                  | string | Primary accent color (hex) for buttons, links, active states. Example: `"#6852D6"`       |
| Primary Text Light (`primaryTextLight`)     | string | Main text color in light mode (hex). Example: `"#141414"`                                |
| Primary Text Dark (`primaryTextDark`)       | string | Main text color in dark mode (hex). Example: `"#FFFFFF"`                                 |
| Secondary Text Light (`secondaryTextLight`) | string | Secondary text color in light mode (hex) for timestamps, subtitles. Example: `"#727272"` |
| Secondary Text Dark (`secondaryTextDark`)   | string | Secondary text color in dark mode (hex) for timestamps, subtitles. Example: `"#989898"`  |

### 4.3 Typography

| Setting       | Type   | What It Does                                                          |
| ------------- | ------ | --------------------------------------------------------------------- |
| Font (`font`) | string | Font family: `'roboto'`, `'arial'`, `'inter'`, or `'times new roman'` |
| Size (`size`) | string | Text size and spacing: `'default'`, `'compact'`, or `'comfortable'`   |

***

## Settings Overview

Below is the complete settings structure with default values. Update these in your `cometchat-builder-settings.json` file to customize your chat experience.

```json theme={null}
{
  "builderId": "your-builder-id",
  "settings": {
    "chatFeatures": {
      "coreMessagingExperience": {
        "typingIndicator": true,
        "threadConversationAndReplies": true,
        "photosSharing": true,
        "videoSharing": true,
        "audioSharing": true,
        "fileSharing": true,
        "editMessage": true,
        "deleteMessage": true,
        "messageDeliveryAndReadReceipts": true,
        "userAndFriendsPresence": true,
        "conversationAndAdvancedSearch": true,
        "moderation": true,
        "quotedReplies": false,
        "markAsUnread": false
      },
      "deeperUserEngagement": {
        "mentions": true,
        "mentionAll": true,
        "reactions": true,
        "messageTranslation": true,
        "polls": true,
        "collaborativeWhiteboard": true,
        "collaborativeDocument": true,
        "voiceNotes": true,
        "emojis": true,
        "stickers": true,
        "userInfo": true,
        "groupInfo": true
      },
      "aiUserCopilot": {
        "conversationStarter": false,
        "conversationSummary": false,
        "smartReply": false
      },
      "userManagement": {
        "friendsOnly": false
      },
      "groupManagement": {
        "createGroup": true,
        "addMembersToGroups": true,
        "joinLeaveGroup": true,
        "deleteGroup": true,
        "viewGroupMembers": true
      },
      "moderatorControls": {
        "kickUsers": true,
        "banUsers": true,
        "promoteDemoteMembers": true,
        "reportMessage": true
      },
      "privateMessagingWithinGroups": {
        "sendPrivateMessageToGroupMembers": true
      },
      "inAppSounds": {
        "incomingMessageSound": true,
        "outgoingMessageSound": true
      }
    },
    "callFeatures": {
      "voiceAndVideoCalling": {
        "oneOnOneVoiceCalling": true,
        "oneOnOneVideoCalling": true,
        "groupVideoConference": true,
        "groupVoiceConference": true
      }
    },
    "layout": {
      "withSideBar": true,
      "tabs": ["chats", "calls", "users", "groups"],
      "chatType": "user"
    },
    "style": {
      "theme": "system",
      "color": {
        "brandColor": "#6852D6",
        "primaryTextLight": "#141414",
        "primaryTextDark": "#FFFFFF",
        "secondaryTextLight": "#727272",
        "secondaryTextDark": "#989898"
      },
      "typography": {
        "font": "roboto",
        "size": "default"
      }
    }
  }
}
```

***

## Dashboard Feature Requirements

Some features require additional configuration in the [CometChat Dashboard](https://app.cometchat.com) before they can be used:

<Note>
  **AI Copilot Features** (Conversation Starter, Conversation Summary, Smart Reply)

  * Requires an OpenAI API key configured in the Dashboard under **AI > Settings**
</Note>

<Note>
  **Stickers**

  * Requires sticker packs to be configured in the Dashboard under **Chat & Messaging > Stickers**
</Note>

<Note>
  **Polls**

  * Requires the Polls extension to be enabled in the Dashboard under **Extensions > Polls**
</Note>

<Note>
  **Collaborative Whiteboard & Document**

  * Requires the respective extensions to be enabled in the Dashboard under **Extensions**
</Note>

<Note>
  **Message Translation**

  * Requires the Message Translation extension to be enabled in the Dashboard under **Extensions > Message Translation**
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    Understand the organization of the builder components and generated code.
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Modify component props, styling, and behavior for deeper customization.
  </Card>
</CardGroup>